Back to Details

oo-component-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OO Component Documentation

面向对象（OO）组件文档

Create new documentation for an object-oriented component or update an existing component documentation file by analyzing the current implementation.
通过分析当前实现，为面向对象组件创建新文档或更新现有组件文档文件。

Determine the mode first

首先确定模式

Choose the workflow before writing anything:
  1. Use update mode when the user provides an existing documentation Markdown file, points to a docs path, or explicitly asks to refresh or revise existing documentation. Follow references/update-mode.md.
  2. Use create mode when the user provides a source file or folder, points to a component path, or asks to generate documentation from code. Follow references/create-mode.md.
  3. If both code and an existing documentation file are provided, treat the existing documentation file as the output target and use the current source code as the source of truth.
  4. If the request is ambiguous, infer the mode from the path type whenever possible: existing Markdown documentation file means update mode; source/component path means create mode.
在开始撰写前选择工作流：
  1. 当用户提供现有文档Markdown文件、指定文档路径，或明确要求刷新/修订现有文档时，使用更新模式。请遵循references/update-mode.md。
  2. 当用户提供源文件或文件夹、指定组件路径，或要求从代码生成文档时，使用创建模式。请遵循references/create-mode.md。
  3. 如果同时提供了代码和现有文档文件，则将现有文档文件作为输出目标，并将当前源代码作为事实依据。
  4. 如果请求不明确，请尽可能从路径类型推断模式：现有Markdown文档文件表示更新模式；源/组件路径表示创建模式。

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 the primary audience
  • DOC-001：遵循C4模型文档层级（Context、Containers、Components、Code）
  • DOC-002：与Arc42软件架构文档模板保持一致
  • DOC-003：符合IEEE 1016软件设计描述标准
  • DOC-004：采用敏捷文档原则（仅创建有价值的必要文档）
  • DOC-005：以开发人员和维护人员为主要受众

Shared analysis guidance

通用分析指南

  • ANA-001: Determine the primary component boundary and whether the input represents a folder, file, or existing documentation target
  • ANA-002: Examine source code files for class structures, inheritance, composition, and interfaces
  • ANA-003: Identify design patterns, architectural decisions, and integration points
  • ANA-004: Document or refresh public APIs, interfaces, dependencies, and usage patterns
  • ANA-005: Capture method parameters, return values, asynchronous behavior, exceptions, and lifecycle concerns
  • ANA-006: Assess performance, security, reliability, maintainability, and extensibility characteristics
  • ANA-007: Infer data flow, collaboration patterns, and relationships with surrounding components
  • ANA-008: Keep the documentation grounded in the implementation; avoid inventing behavior that is not supported by the code
  • ANA-001：确定主要组件边界，以及输入内容是文件夹、文件还是现有文档目标
  • ANA-002：检查源代码文件的类结构、继承关系、组合关系和接口
  • ANA-003：识别设计模式、架构决策和集成点
  • ANA-004：记录或更新公共API、接口、依赖关系和使用模式
  • ANA-005：记录方法参数、返回值、异步行为、异常和生命周期相关事项
  • ANA-006：评估性能、安全性、可靠性、可维护性和可扩展性特征
  • ANA-007：推断数据流、协作模式以及与周边组件的关系
  • ANA-008：文档需基于实际实现；避免编造代码不支持的行为

Shared output requirements

通用输出要求

  • Use assets/documentation-template.md as the canonical section checklist and baseline structure.
  • Keep the output in Markdown with a clear heading hierarchy, tables where useful, code blocks for examples, and Mermaid diagrams when architecture relationships need to be visualized.
  • Make examples and interface descriptions match the current implementation instead of generic placeholders.
  • Include only information that can be supported by the code, project structure, configuration, or clearly stated assumptions.
  • When source coverage is incomplete, document the limitation explicitly instead of guessing.
  • 将assets/documentation-template.md作为标准章节检查清单和基线结构。
  • 输出采用Markdown格式，具备清晰的标题层级，在合适的地方使用表格，用代码块展示示例，当需要可视化架构关系时使用Mermaid图表。
  • 示例和接口描述需与当前实现一致，而非使用通用占位符。
  • 仅包含可由代码、项目结构、配置或明确说明的假设所支持的信息。
  • 当源代码覆盖不完整时，需明确记录该限制，而非猜测。

Language-specific optimizations

特定语言优化

  • LNG-001: C#/.NET - async/await, dependency injection, configuration, disposal, options patterns
  • LNG-002: Java - Spring framework, annotations, exception handling, packaging, dependency injection
  • LNG-003: TypeScript/JavaScript - modules, async patterns, types, npm dependencies, runtime boundaries
  • LNG-004: Python - packages, virtual environments, type hints, testing, dependency management
  • LNG-001：C#/.NET - async/await、依赖注入、配置、资源释放、选项模式
  • LNG-002：Java - Spring框架、注解、异常处理、打包、依赖注入
  • LNG-003：TypeScript/JavaScript - 模块、异步模式、类型、npm依赖、运行时边界
  • LNG-004：Python - 包、虚拟环境、类型提示、测试、依赖管理

Error handling

错误处理

  • ERR-001: If the path does not exist, explain what path was expected and whether the skill needs a source path or an existing documentation file
  • ERR-002: If no relevant source files are found, document the gap and suggest the likely locations to inspect next
  • ERR-003: If the documentation target cannot be inferred from the request, state the ambiguity and ask for the missing path only when inference is not possible
  • ERR-004: If the code uses non-standard architectural patterns, document the custom approach rather than forcing it into a generic pattern
  • ERR-005: If source access is incomplete, continue with available evidence and clearly call out any unsupported sections
  • ERR-001：如果路径不存在，说明预期的路径类型，以及该技能需要的是源路径还是现有文档文件
  • ERR-002：如果未找到相关源文件，记录该缺口并建议下一步可能需要检查的位置
  • ERR-003：如果无法从请求中推断出文档目标，说明模糊点，仅在无法推断时请求提供缺失的路径
  • ERR-004：如果代码使用非标准架构模式，记录该自定义方法，而非强行套用通用模式
  • ERR-005：如果源代码访问不完整，基于现有信息继续处理，并明确标注所有未得到支持的章节

Workflow

工作流程

  1. Determine whether the task is create mode or update mode.
  2. Inspect the component implementation and any related files needed to understand its public surface area and internal structure.
  3. Use assets/documentation-template.md as the shared documentation scaffold.
  4. Apply the mode-specific rules in references/create-mode.md or references/update-mode.md.
  5. Produce or revise the documentation so that diagrams, examples, interfaces, dependencies, and quality attributes reflect the current implementation.
  1. 判断任务是创建模式还是更新模式。
  2. 检查组件实现以及所有有助于理解其公共接口和内部结构的相关文件。
  3. 将assets/documentation-template.md作为通用文档框架。
  4. 应用references/create-mode.md或references/update-mode.md中的特定模式规则。
  5. 生成或修订文档，确保图表、示例、接口、依赖关系和质量属性均反映当前实现。

Completion criteria

完成标准

  • The documentation clearly identifies the component purpose, architecture, interfaces, implementation details, usage patterns, quality attributes, and references.
  • Front matter fields are accurate for the selected mode.
  • Examples and diagrams match the implementation.
  • Any unknowns, gaps, or assumptions are explicitly called out.
  • 文档清晰说明组件的用途、架构、接口、实现细节、使用模式、质量属性和参考资料。
  • 所选模式的前置元数据字段准确无误。
  • 示例和图表与实现一致。
  • 所有未知项、缺口或假设均明确标注。