Back to Details

update-oo-component-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Update Standard OO Component Documentation

更新标准面向对象（OO）组件文档

Update the existing documentation file at: 
${file}
by analyzing the corresponding component code.
Extract the component path from the existing documentation's front matter (
component_path
field) or infer it from the documentation content. Analyze the current component implementation and update the documentation accordingly.
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
Analysis Instructions:
  • ANA-001: Read existing documentation to understand component context and structure
  • ANA-002: Identify component path from front matter or content analysis
  • ANA-003: Examine current source code files for class structures and inheritance
  • ANA-004: Compare existing documentation with current implementation
  • ANA-005: Identify design patterns and architectural changes
  • ANA-006: Update public APIs, interfaces, and dependencies
  • ANA-007: Recognize new/changed creational/structural/behavioral patterns
  • ANA-008: Update method parameters, return values, exceptions
  • ANA-009: Reassess performance, security, reliability, maintainability
  • ANA-010: Update integration patterns and data flow
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
Update Strategy:
  • UPD-001: Preserve existing documentation structure and format
  • UPD-002: Update 
    last_updated
    field to current date
  • UPD-003: Maintain version history in front matter if present
  • UPD-004: Add new sections if component has significantly expanded
  • UPD-005: Mark deprecated features or breaking changes
  • UPD-006: Update examples to reflect current API
  • UPD-007: Refresh dependency lists and versions
  • UPD-008: Update mermaid diagrams to reflect current architecture
Error Handling:
  • ERR-001: Documentation file doesn't exist - provide guidance on file location
  • ERR-002: Component path not found in documentation - request clarification
  • ERR-003: Source code has moved - suggest updated paths
  • ERR-004: Major architectural changes - highlight breaking changes
  • ERR-005: Insufficient access to source - document limitations
Output Format:
Update the existing Markdown file maintaining its structure while refreshing content to match current implementation. Preserve formatting, heading hierarchy, and existing organizational decisions.
Required Documentation Structure:
Update the existing documentation following the same template structure, ensuring all sections reflect current implementation:
md
---
title: [Component Name] - Technical Documentation
component_path: [Current component path]
version: [Updated version if applicable]
date_created: [Original creation date - preserve]
last_updated: [YYYY-MM-DD - update to current date]
owner: [Preserve existing or update if changed]
tags: [Update tags as needed based on current functionality]
---
通过分析对应的组件代码，更新位于
${file}
的现有文档文件。
从现有文档的前置元数据（
component_path
字段）中提取组件路径，或从文档内容中推断路径。分析当前组件实现并相应更新文档。
文档标准：
  • DOC-001：遵循C4 Model文档层级（上下文、容器、组件、代码）
  • DOC-002：与Arc42软件架构文档模板保持一致
  • DOC-003：符合IEEE 1016软件设计描述标准
  • DOC-004：采用敏捷文档原则（仅提供能带来价值的必要文档）
  • DOC-005：以开发人员和维护人员为主要受众
分析说明：
  • ANA-001：阅读现有文档，了解组件上下文和结构
  • ANA-002：从前置元数据或内容分析中确定组件路径
  • ANA-003：检查当前源代码文件的类结构和继承关系
  • ANA-004：对比现有文档与当前实现
  • ANA-005：识别设计模式和架构变更
  • ANA-006：更新公共API、接口和依赖关系
  • ANA-007：识别新增/变更的创建型/结构型/行为型模式
  • ANA-008：更新方法参数、返回值和异常
  • ANA-009：重新评估性能、安全性、可靠性和可维护性
  • ANA-010：更新集成模式和数据流
语言特定优化：
  • LNG-001：C#/.NET - async/await、依赖注入、配置、资源释放
  • LNG-002：Java - Spring框架、注解、异常处理、打包
  • LNG-003：TypeScript/JavaScript - 模块、异步模式、类型、npm
  • LNG-004：Python - 包、虚拟环境、类型提示、测试
更新策略：
  • UPD-001：保留现有文档结构和格式
  • UPD-002：将
    last_updated
    字段更新为当前日期
  • UPD-003：如果存在前置元数据中的版本历史，则予以保留
  • UPD-004：如果组件已大幅扩展，添加新章节
  • UPD-005：标记已弃用功能或破坏性变更
  • UPD-006：更新示例以反映当前API
  • UPD-007：刷新依赖列表和版本
  • UPD-008：更新mermaid图表以反映当前架构
错误处理：
  • ERR-001：文档文件不存在 - 提供文件位置指导
  • ERR-002：文档中未找到组件路径 - 请求澄清
  • ERR-003：源代码已移动 - 建议更新后的路径
  • ERR-004：重大架构变更 - 突出显示破坏性变更
  • ERR-005：源代码访问权限不足 - 记录限制
输出格式：
更新现有Markdown文件，保留其结构同时刷新内容以匹配当前实现。保留格式、标题层级和现有组织决策。
必填文档结构：
按照相同模板结构更新现有文档，确保所有章节反映当前实现：
md
---
title: [Component Name] - Technical Documentation
component_path: [Current component path]
version: [Updated version if applicable]
date_created: [Original creation date - preserve]
last_updated: [YYYY-MM-DD - update to current date]
owner: [Preserve existing or update if changed]
tags: [Update tags as needed based on current functionality]
---

[Component Name] Documentation

[Component Name] Documentation

[Update introduction to reflect current component purpose and capabilities]
[Update introduction to reflect current component purpose and capabilities]

1. Component Overview

1. Component Overview

Purpose/Responsibility

Purpose/Responsibility

  • OVR-001: Update component's primary responsibility
  • OVR-002: Refresh scope (included/excluded functionality)
  • OVR-003: Update system context and relationships
  • OVR-001: Update component's primary responsibility
  • OVR-002: Refresh scope (included/excluded functionality)
  • OVR-003: Update system context and relationships

2. Architecture Section

2. Architecture Section

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

Component Structure and Dependencies Diagram

Component Structure and Dependencies Diagram

Update the mermaid diagram to show current:
  • Component structure - Current classes, interfaces, and their relationships
  • Internal dependencies - How components currently interact within the system
  • External dependencies - Current external libraries, services, databases, APIs
  • Data flow - Current direction of dependencies and interactions
  • Inheritance/composition - Current class hierarchies and composition relationships
mermaid
[Update diagram to reflect current architecture]
Update the mermaid diagram to show current:
  • Component structure - Current classes, interfaces, and their relationships
  • Internal dependencies - How components currently interact within the system
  • External dependencies - Current external libraries, services, databases, APIs
  • Data flow - Current direction of dependencies and interactions
  • Inheritance/composition - Current class hierarchies and composition relationships
mermaid
[Update diagram to reflect current architecture]

3. Interface Documentation

3. Interface Documentation

  • INT-001: Update all public interfaces and current usage patterns
  • INT-002: Refresh method/property reference table with current API
  • INT-003: Update events/callbacks/notification mechanisms
Method/PropertyPurposeParametersReturn TypeUsage Notes
[Update table with current API]
  • INT-001: Update all public interfaces and current usage patterns
  • INT-002: Refresh method/property reference table with current API
  • INT-003: Update events/callbacks/notification mechanisms
Method/PropertyPurposeParametersReturn TypeUsage Notes
[Update table with current API]

4. Implementation Details

4. Implementation Details

  • IMP-001: Update main implementation classes and current responsibilities
  • IMP-002: Refresh configuration requirements and initialization patterns
  • IMP-003: Update key algorithms and business logic
  • IMP-004: Update performance characteristics and bottlenecks
  • IMP-001: Update main implementation classes and current responsibilities
  • IMP-002: Refresh configuration requirements and initialization patterns
  • IMP-003: Update key algorithms and business logic
  • IMP-004: Update performance characteristics and bottlenecks

5. Usage Examples

5. Usage Examples

Basic Usage

Basic Usage

csharp
// Update basic usage example to current API
csharp
// Update basic usage example to current API

Advanced Usage

Advanced Usage

csharp
// Update advanced configuration patterns to current implementation
  • USE-001: Update basic usage examples
  • USE-002: Refresh advanced configuration patterns
  • USE-003: Update best practices and recommended patterns
csharp
// Update advanced configuration patterns to current implementation
  • USE-001: Update basic usage examples
  • USE-002: Refresh advanced configuration patterns
  • USE-003: Update best practices and recommended patterns

6. Quality Attributes

6. Quality Attributes

  • QUA-001: Update security (authentication, authorization, data protection)
  • QUA-002: Refresh performance (characteristics, scalability, resource usage)
  • QUA-003: Update reliability (error handling, fault tolerance, recovery)
  • QUA-004: Refresh maintainability (standards, testing, documentation)
  • QUA-005: Update extensibility (extension points, customization options)
  • QUA-001: Update security (authentication, authorization, data protection)
  • QUA-002: Refresh performance (characteristics, scalability, resource usage)
  • QUA-003: Update reliability (error handling, fault tolerance, recovery)
  • QUA-004: Refresh maintainability (standards, testing, documentation)
  • QUA-005: Update extensibility (extension points, customization options)

7. Reference Information

7. Reference Information

  • REF-001: Update dependencies with current versions and purposes
  • REF-002: Refresh configuration options reference
  • REF-003: Update testing guidelines and mock setup
  • REF-004: Refresh troubleshooting (common issues, error messages)
  • REF-005: Update related documentation links
  • REF-006: Add change history and migration notes for this update
undefined
  • REF-001: Update dependencies with current versions and purposes
  • REF-002: Refresh configuration options reference
  • REF-003: Update testing guidelines and mock setup
  • REF-004: Refresh troubleshooting (common issues, error messages)
  • REF-005: Update related documentation links
  • REF-006: Add change history and migration notes for this update
undefined