oo-component-documentation

面向对象组件文档

通过分析当前实现，为面向对象组件创建新文档，或更新现有的组件文档文件。

首先确定模式

在撰写任何内容之前先选择工作流：

1. 当用户提供现有的文档 Markdown 文件、指向某个文档路径，或明确要求刷新或修订现有文档时，使用更新模式。遵循 references/update-mode.md。
2. 当用户提供源文件或文件夹、指向某个组件路径，或要求根据代码生成文档时，使用创建模式。遵循 references/create-mode.md。
3. 如果同时提供了代码和现有文档文件，则将现有文档文件视为输出目标，并将当前源代码作为事实来源。
4. 如果请求含糊不清，尽可能根据路径类型推断模式：现有 Markdown 文档文件意味着更新模式；源文件/组件路径意味着创建模式。

文档标准

• DOC-001：遵循 C4 模型文档层级（Context、Containers、Components、Code）
• DOC-002：与 Arc42 软件架构文档模板保持一致
• DOC-003：符合 IEEE 1016 软件设计描述标准
• DOC-004：采用敏捷文档原则（仅保留足以创造价值的文档）
• DOC-005：以开发者和维护者作为主要受众

通用分析指导

• ANA-001：确定主要组件边界，以及输入表示的是文件夹、文件还是现有文档目标
• ANA-002：检查源代码文件中的类结构、继承、组合和接口
• ANA-003：识别设计模式、架构决策和集成点
• ANA-004：记录或刷新公共 API、接口、依赖项和使用模式
• ANA-005：捕获方法参数、返回值、异步行为、异常和生命周期相关问题
• ANA-006：评估性能、安全性、可靠性、可维护性和可扩展性特征
• ANA-007：推断数据流、协作模式以及与周围组件的关系
• ANA-008：让文档立足于实现；避免臆造代码不支持的行为

通用输出要求

• 使用 assets/documentation-template.md 作为规范性的章节检查清单和基线结构。
• 输出保持为 Markdown，具有清晰的标题层级、在有用处使用表格、用代码块展示示例，并在需要可视化架构关系时使用 Mermaid 图。
• 让示例和接口描述与当前实现匹配，而不是使用通用占位符。
• 仅包含能够由代码、项目结构、配置或明确陈述的假设所支持的信息。
• 当源代码覆盖不完整时，明确记录该局限性，而不是猜测。

特定语言优化

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

错误处理

• ERR-001：如果路径不存在，请说明期望的路径是什么，以及该技能需要的是源路径还是现有的文档文件
• ERR-002：如果未找到相关文件，请记录该缺口，并建议接下来可能需要检查的位置
• ERR-003：如果无法从请求中推断出文档目标，请说明该歧义，仅在无法推断时才询问缺失的路径
• ERR-004：如果代码使用了非标准架构模式，请记录其自定义方法，而不是强行将其套入通用模式
• ERR-005：如果源访问不完整，请基于现有证据继续，并明确标注任何不受支持的部分

工作流

1. 确定任务是创建模式还是更新模式。
2. 检查组件实现以及理解其公共接口面和内部结构所需的任何相关文件。
3. 使用 assets/documentation-template.md 作为共享文档脚手架。
4. 应用 references/create-mode.md 或 references/update-mode.md 中特定于模式的规则。
5. 生成或修订文档，使图表、示例、接口、依赖项和质量属性反映当前实现。

完成标准

• 文档清晰地标识出组件用途、接口、实现细节、使用模式、质量属性和参考。
• Front matter 字段对所选内容准确无误。
• 示例和图表与实现一致。
• 任何未知项、缺口或假设均被明确标注。