From a99d68a103c77ec43b00aa852b2693c22e093078 Mon Sep 17 00:00:00 2001 From: Oleksandr Bezdieniezhnykh Date: Fri, 5 Dec 2025 15:46:28 +0200 Subject: [PATCH] add documentation scommand , revised gen component command's component format --- .../2.planning/2.10_gen_components.md | 45 ++++++++++------ .../3.10_implement_component.md | 2 +- .../5.refactoring/5.10_documentation.md | 54 +++++++++++++++++++ ...omponent_flight_processing_engine_spec.md} | 0 4 files changed, 84 insertions(+), 17 deletions(-) create mode 100644 .cursor/commands/5.refactoring/5.10_documentation.md rename _docs/02_components/02_flight_processor/{02.2._spec_flight_processing_engine_spec.md => 02.2._component_flight_processing_engine_spec.md} (100%) diff --git a/.cursor/commands/2.planning/2.10_gen_components.md b/.cursor/commands/2.planning/2.10_gen_components.md index 9bfd28d..38f06da 100644 --- a/.cursor/commands/2.planning/2.10_gen_components.md +++ b/.cursor/commands/2.planning/2.10_gen_components.md @@ -26,22 +26,35 @@ - Solution draft could be incomplete, so add all necessary components to meet acceptance criteria and restrictions - When you've got full understanding of how exactly each component will interact with each other, create components -## Output - - Store description of each component to the file `_docs/02_components/[##]_[component_name]/[##]._component_[component_name].md` with the next structure: - - Component Name - - Detailed description - - API methods, for each method: - - Name - - Detailed description - - Which component/system will use this method - - Input - - Output - - Description of input and output data in case if it not obvious - - Test cases for the method - - Integration tests for the component if needed. - - Non-functional tests for the component if needed. - - Store Extensions and Helpers to support functionality across multiple components to a separate folder `_docs/02_components/helpers`. - - Generate draw.io components diagram shows relations between components. +## Output Format +Store description of each component to the file `_docs/02_components/[##]_[component_name]/[##]._component_[component_name].md` with the next structure: + 1. High-level overview + - **Purpose:** A concise summary of what this component does and its role in the larger system. + - **Architectural Pattern:** Identify the design patterns used (e.g., Singleton, Observer, Factory). + 2. Logic & Architecture + - **Control Flow Diagram:** + - Generate a `graph TD` or `sequenceDiagram` in Mermaid syntax. + - Generate draw.io components diagram shows relations between components. + 3. API Reference. Create a table for eac function or method with the next columns: + - Name + - Description + - Input + - Output + - Description of input and output data in case if it is not obvious + - Test cases which could be for the method + 4. Implementation Details + - **Algorithmic Complexity:** Analyze Time (Big O) and Space complexity for critical methods. + - **State Management:** Explain how this component handles state (local vs. global). + - **Dependencies:** List key external libraries and their purpose here. + 5. Tests + - Integration tests for the component if needed. + - Non-functional tests for the component if needed. + 6. Extensions and Helpers + - Store Extensions and Helpers to support functionality across multiple components to a separate folder `_docs/02_components/helpers`. + 7. Caveats & Edge Cases + - Known limitations + - Potential race conditions + - Potential performance bottlenecks. ## Notes - Strongly follow Single Responsibility Principle during creation of components. diff --git a/.cursor/commands/3.implementation/3.10_implement_component.md b/.cursor/commands/3.implementation/3.10_implement_component.md index 717d32a..70c459f 100644 --- a/.cursor/commands/3.implementation/3.10_implement_component.md +++ b/.cursor/commands/3.implementation/3.10_implement_component.md @@ -26,7 +26,7 @@ - Read carefully all the component features in the component_folder: `@_docs/02_components/[##]_[component_name]/[##].[##]_feature_[feature_name]` - Investgate in internet what are the best way and tools to implement component and its features - During the investigation is is possible that found solutions required architecturally reorganization of the features. It is ok, propose that and if user agrees, include reorganization in the build feature plan. Also it is possible that interface could be changed or even removed or added new one. It is ok. - - Make sure feature is connected and communicated properly with other features and existing code + - Make sure each feature is connected and communicated properly with other features and existing code - If component has dependency on another one, create temporary mock for the dependency - Create unit tests from the Test cases description, run it and make sure the result is a success - Create integration test for the feature, run and make sure the result is a success diff --git a/.cursor/commands/5.refactoring/5.10_documentation.md b/.cursor/commands/5.refactoring/5.10_documentation.md new file mode 100644 index 0000000..c85e8c4 --- /dev/null +++ b/.cursor/commands/5.refactoring/5.10_documentation.md @@ -0,0 +1,54 @@ +# Create a comprehensive documentation from existing codebase + +## Role + You are a Principal Software Architect and Technical Communication Expert. You are renowned for your ability to explain complex codebases with clarity, technical rigor, and architectural insight. + +## Task + Generate production-grade documentation that serves both maintenance engineers (deep details) and consuming developers (high-level usage). + +## Core Directives: + - Truthfulness: Never invent features. Ground every claim in the provided code. + - Clarity: Use professional, third-person objective tone. Avoid fluff ("This code does..."). + - Completeness: Document every public interface, but summarize private internals unless critical. + - Visuals: Always visualize complex logic using Mermaid.js. + +## Proces: + 1. Analyze the project structure, form rough understanding from the directories, projects and files + 2. Go file by file, analyze each method, convert each method to short api reference description, form the rough flow diagram. You can write interim summary for each file + 3. Analyze summaries and code, analyze connections between components, form more detailed structure by the format described in Output Format section + +## Output Format +Store description of each component to the file `_docs/02_components/[##]_[component_name]/[##]._component_[component_name].md` with the next structure: + 1. High-level overview + - **Purpose:** A concise summary of what this component does and its role in the larger system. + - **Architectural Pattern:** Identify the design patterns used (e.g., Singleton, Observer, Factory). + 2. Logic & Architecture + - **Control Flow Diagram:** + - Generate a `graph TD` or `sequenceDiagram` in Mermaid syntax. + - Generate draw.io components diagram shows relations between components. + 3. API Reference. Create a table for eac function or method with the next columns: + - Name + - Description + - Input + - Output + - Description of input and output data in case if it is not obvious + - Test cases which could be for the method + 4. Implementation Details + - **Algorithmic Complexity:** Analyze Time (Big O) and Space complexity for critical methods. + - **State Management:** Explain how this component handles state (local vs. global). + - **Dependencies:** List key external libraries and their purpose here. + 5. Tests + - Integration tests for the component if needed. + - Non-functional tests for the component if needed. + 6. Extensions and Helpers + - Store Extensions and Helpers to support functionality across multiple components to a separate folder `_docs/02_components/helpers`. + 7. Caveats & Edge Cases + - Known limitations + - Potential race conditions + - Potential performance bottlenecks. + +## Notes + Do final checks: + - Whether all the parameters are captured + - Is the Mermaid diagram syntactically correct + - Should be explained why the code works, not just how \ No newline at end of file diff --git a/_docs/02_components/02_flight_processor/02.2._spec_flight_processing_engine_spec.md b/_docs/02_components/02_flight_processor/02.2._component_flight_processing_engine_spec.md similarity index 100% rename from _docs/02_components/02_flight_processor/02.2._spec_flight_processing_engine_spec.md rename to _docs/02_components/02_flight_processor/02.2._component_flight_processing_engine_spec.md