create-oo-component-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate Standard OO Component Documentation

生成标准化面向对象组件文档

Create comprehensive documentation for the object-oriented component(s) at:

${input:ComponentPath}

Analyze the component by examining code in the provided path. If folder, analyze all source files. If single file, treat as main component and analyze related files in same directory.

为路径

${input:ComponentPath}

下的面向对象组件创建全面的文档。

通过检查提供路径中的代码来分析组件。如果是文件夹，则分析所有源文件；如果是单个文件，则将其视为主组件并分析同一目录中的相关文件。

Documentation Standards

文档标准

DOC-001: Follow C4 Model documentation levels (Context, Containers, Components, Code)
DOC-002: Align with Arc42 software architecture documentation template
DOC-003: Comply with IEEE 1016 Software Design Description standard
DOC-004: Use Agile Documentation principles (just enough documentation that adds value)
DOC-005: Target developers and maintainers as primary audience

DOC-001：遵循C4 Model文档层级（上下文、容器、组件、代码）
DOC-002：与Arc42软件架构文档模板保持一致
DOC-003：符合IEEE 1016软件设计描述标准
DOC-004：采用敏捷文档原则（仅创建具备价值的必要文档）
DOC-005：以开发人员和维护人员为主要受众

Analysis Instructions

分析说明

ANA-001: Determine path type (folder vs single file) and identify primary component
ANA-002: Examine source code files for class structures and inheritance
ANA-003: Identify design patterns and architectural decisions
ANA-004: Document public APIs, interfaces, and dependencies
ANA-005: Recognize creational/structural/behavioral patterns
ANA-006: Document method parameters, return values, exceptions
ANA-007: Assess performance, security, reliability, maintainability
ANA-008: Infer integration patterns and data flow

ANA-001：确定路径类型（文件夹或单个文件）并识别主组件
ANA-002：检查源文件中的类结构和继承关系
ANA-003：识别设计模式和架构决策
ANA-004：记录公共API、接口和依赖关系
ANA-005：识别创建型/结构型/行为型模式
ANA-006：记录方法参数、返回值和异常
ANA-007：评估性能、安全性、可靠性和可维护性
ANA-008：推断集成模式和数据流

Language-Specific Optimizations

语言特定优化

LNG-001: C#/.NET - async/await, dependency injection, configuration, disposal
LNG-002: Java - Spring framework, annotations, exception handling, packaging
LNG-003: TypeScript/JavaScript - modules, async patterns, types, npm
LNG-004: Python - packages, virtual environments, type hints, testing

LNG-001：C#/.NET - async/await、依赖注入、配置、资源释放
LNG-002：Java - Spring框架、注解、异常处理、打包
LNG-003：TypeScript/JavaScript - 模块、异步模式、类型、npm
LNG-004：Python - 包、虚拟环境、类型提示、测试

Error Handling

错误处理

ERR-001: Path doesn't exist - provide correct format guidance
ERR-002: No source files found - suggest alternative locations
ERR-003: Unclear structure - document findings and request clarification
ERR-004: Non-standard patterns - document custom approaches
ERR-005: Insufficient code - focus on available information, highlight gaps

ERR-001：路径不存在 - 提供正确格式指导
ERR-002：未找到源文件 - 建议替代位置
ERR-003：结构不清晰 - 记录发现的内容并请求澄清
ERR-004：非标准模式 - 记录自定义实现方式
ERR-005：代码不足 - 聚焦现有信息，突出空白点

Output Format

输出格式

Generate well-structured Markdown with clear heading hierarchy, code blocks, tables, bullet points, and proper formatting for readability and maintainability.

生成结构清晰的Markdown文档，具备明确的标题层级、代码块、表格、项目符号，以及便于阅读和维护的格式。

File Location

文件位置

The documentation should be saved in the

/docs/components/

directory and named according to the convention:

[component-name]-documentation.md

文档应保存至

/docs/components/

目录，并按照命名规范

[component-name]-documentation.md

命名。

Required Documentation Structure

所需文档结构

The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:

---
title: [Component Name] - Technical Documentation
component_path: `${input:ComponentPath}`
version: [Optional: e.g., 1.0, Date]
date_created: [YYYY-MM-DD]
last_updated: [Optional: YYYY-MM-DD]
owner: [Optional: Team/Individual responsible for this component]
tags: [Optional: List of relevant tags or categories, e.g., `component`,`service`,`tool`,`infrastructure`,`documentation`,`architecture` etc]
---

文档文件必须遵循以下模板，确保所有部分均已适当填写。Markdown的前置元数据应按照以下示例正确结构化：

---
title: [组件名称] - 技术文档
component_path: `${input:ComponentPath}`
version: [可选：例如 1.0、日期]
date_created: [YYYY-MM-DD]
last_updated: [可选：YYYY-MM-DD]
owner: [可选：负责该组件的团队/个人]
tags: [可选：相关标签或类别列表，例如 `component`,`service`,`tool`,`infrastructure`,`documentation`,`architecture` 等]
---

[Component Name] Documentation

[组件名称]文档

[A short concise introduction to the component and its purpose within the system.]

[对组件及其在系统中的用途的简短介绍。]

1. Component Overview

1. 组件概述

Purpose/Responsibility

用途/职责

OVR-001: State component's primary responsibility
OVR-002: Define scope (included/excluded functionality)
OVR-003: Describe system context and relationships

OVR-001：说明组件的主要职责
OVR-002：定义范围（包含/排除的功能）
OVR-003：描述系统上下文和关系

2. Architecture Section

2. 架构部分

ARC-001: Document design patterns used (Repository, Factory, Observer, etc.)
ARC-002: List internal and external dependencies with purposes
ARC-003: Document component interactions and relationships
ARC-004: Include visual diagrams (UML class, sequence, component)
ARC-005: Create mermaid diagram showing component structure, relationships, and dependencies

ARC-001：记录所使用的设计模式（仓库模式、工厂模式、观察者模式等）
ARC-002：列出内部和外部依赖及其用途
ARC-003：记录组件交互和关系
ARC-004：包含可视化图表（UML类图、序列图、组件图）
ARC-005：创建展示组件结构、关系和依赖的Mermaid图表

Component Structure and Dependencies Diagram

组件结构与依赖关系图

Include a comprehensive mermaid diagram that shows:

Component structure - Main classes, interfaces, and their relationships
Internal dependencies - How components interact within the system
External dependencies - External libraries, services, databases, APIs
Data flow - Direction of dependencies and interactions
Inheritance/composition - Class hierarchies and composition relationships

mermaid

graph TD
    subgraph "Component System"
        A[Main Component] --> B[Internal Service]
        A --> C[Internal Repository]
        B --> D[Business Logic]
        C --> E[Data Access Layer]
    end

    subgraph "External Dependencies"
        F[External API]
        G[Database]
        H[Third-party Library]
        I[Configuration Service]
    end

    A --> F
    E --> G
    B --> H
    A --> I

    classDiagram
        class MainComponent {
            +property: Type
            +method(): ReturnType
            +asyncMethod(): Promise~Type~
        }
        class InternalService {
            +businessOperation(): Result
        }
        class ExternalAPI {
            <<external>>
            +apiCall(): Data
        }

        MainComponent --> InternalService
        MainComponent --> ExternalAPI

包含一个全面的Mermaid图表，展示：

组件结构 - 主类、接口及其关系
内部依赖 - 组件在系统内的交互方式
外部依赖 - 外部库、服务、数据库、API
数据流 - 依赖和交互的方向
继承/组合 - 类层次结构和组合关系

mermaid

graph TD
    subgraph "Component System"
        A[Main Component] --> B[Internal Service]
        A --> C[Internal Repository]
        B --> D[Business Logic]
        C --> E[Data Access Layer]
    end

    subgraph "External Dependencies"
        F[External API]
        G[Database]
        H[Third-party Library]
        I[Configuration Service]
    end

    A --> F
    E --> G
    B --> H
    A --> I

    classDiagram
        class MainComponent {
            +property: Type
            +method(): ReturnType
            +asyncMethod(): Promise~Type~
        }
        class InternalService {
            +businessOperation(): Result
        }
        class ExternalAPI {
            <<external>>
            +apiCall(): Data
        }

        MainComponent --> InternalService
        MainComponent --> ExternalAPI

3. Interface Documentation

3. 接口文档

INT-001: Document all public interfaces and usage patterns
INT-002: Create method/property reference table
INT-003: Document events/callbacks/notification mechanisms

Method/Property	Purpose	Parameters	Return Type	Usage Notes
[Name]	[Purpose]	[Parameters]	[Type]	[Notes]

INT-001：记录所有公共接口和使用模式
INT-002：创建方法/属性参考表
INT-003：记录事件/回调/通知机制

方法/属性	用途	参数	返回类型	使用说明
[名称]	[用途]	[参数]	[类型]	[说明]

4. Implementation Details

4. 实现细节

IMP-001: Document main implementation classes and responsibilities
IMP-002: Describe configuration requirements and initialization
IMP-003: Document key algorithms and business logic
IMP-004: Note performance characteristics and bottlenecks

IMP-001：记录主要实现类及其职责
IMP-002：描述配置要求和初始化过程
IMP-003：记录关键算法和业务逻辑
IMP-004：说明性能特征和瓶颈

5. Usage Examples

5. 使用示例

Basic Usage

基础用法

csharp

// Basic usage example
var component = new ComponentName();
component.DoSomething();

csharp

// Basic usage example
var component = new ComponentName();
component.DoSomething();

Advanced Usage

高级用法

csharp

// Advanced configuration patterns
var options = new ComponentOptions();
var component = ComponentFactory.Create(options);
await component.ProcessAsync(data);

USE-001: Provide basic usage examples
USE-002: Show advanced configuration patterns
USE-003: Document best practices and recommended patterns

csharp

// Advanced configuration patterns
var options = new ComponentOptions();
var component = ComponentFactory.Create(options);
await component.ProcessAsync(data);

USE-001：提供基础用法示例
USE-002：展示高级配置模式
USE-003：记录最佳实践和推荐模式

6. Quality Attributes

6. 质量属性

QUA-001: Security (authentication, authorization, data protection)
QUA-002: Performance (characteristics, scalability, resource usage)
QUA-003: Reliability (error handling, fault tolerance, recovery)
QUA-004: Maintainability (standards, testing, documentation)
QUA-005: Extensibility (extension points, customization options)

QUA-001：安全性（身份验证、授权、数据保护）
QUA-002：性能（特征、可扩展性、资源使用）
QUA-003：可靠性（错误处理、容错能力、恢复机制）
QUA-004：可维护性（标准、测试、文档）
QUA-005：可扩展性（扩展点、自定义选项）

7. Reference Information

7. 参考信息

REF-001: List dependencies with versions and purposes
REF-002: Complete configuration options reference
REF-003: Testing guidelines and mock setup
REF-004: Troubleshooting (common issues, error messages)
REF-005: Related documentation links
REF-006: Change history and migration notes

undefined

REF-001：列出依赖项及其版本和用途
REF-002：完整的配置选项参考
REF-003：测试指南和模拟设置
REF-004：故障排除（常见问题、错误信息）
REF-005：相关文档链接
REF-006：变更历史和迁移说明

undefined