源代码技术文档智能生成器

## 技能概述

源代码技术文档智能生成器是一款专为开发者设计的自动化文档编写工具。它能够深入解析源代码中的注释块、函数签名、参数定义及返回值说明，并将其转化为结构清晰、内容完整的技术文档。本技能支持多种主流编程语言与注释规范，可大幅减少开发者手动编写文档的工作量，确保代码与文档的同步性。

## 适用场景

- 为开源项目自动生成 API 参考文档与开发者手册
- 为团队内部代码库编写统一的维护说明文档
- 将遗留系统代码快速转换为可读的技术说明
- 为新入职员工提供代码库的快速入门指南
- 在代码审查过程中自动产出对应的接口说明

## 支持的编程语言

本技能广泛支持 Python、JavaScript、TypeScript、Java、Go、C/C++、C#、Rust、PHP、Ruby 等主流编程语言，并能够识别 JSDoc、docstring（Google/NumPy/Sphinx 风格）、Javadoc、GoDoc、PHPDoc 等多种注释格式。

## 调用步骤

1. **准备源代码**：确保待处理的代码中包含规范的注释块，函数命名清晰、参数定义完整。
2. **明确文档需求**：向本技能说明文档的目标受众（初级开发者、资深工程师或终端用户）以及文档类型（API 文档、模块说明、使用手册等）。
3. **提供代码内容**：可直接粘贴代码片段，也可指定需要分析的源文件路径或代码仓库地址。
4. **指定输出格式**：选择 Markdown、HTML、reStructuredText 或纯文本等目标文档格式。
5. **审阅与优化**：根据生成的文档初稿，结合实际业务逻辑进行必要的补充、修正与润色。

## 文档输出结构

生成的技术文档通常包含以下标准部分：

- **模块概述**：文件或模块的核心功能简介
- **函数/方法列表**：每个函数的名称、签名、所在位置
- **参数说明**：参数名称、类型、含义、是否必填及默认值
- **返回值说明**：返回类型、含义及可能的取值范围
- **异常说明**：可能抛出的异常类型及触发条件
- **使用示例**：从代码注释中提取的调用示例代码片段
- **版本与变更记录**：如注释中包含的版本与作者信息

## 注意事项

- 代码注释的质量直接决定生成文档的质量，建议在编写代码时同步规范注释风格。
- 涉及复杂业务逻辑时，应在注释中补充上下文说明与使用场景，便于生成更准确的文档。
- 自动生成的文档建议由开发者进行人工审阅，以确保技术细节的准确性与完整性。
- 对于完全缺少注释的代码，生成结果可能不完整或不准确，需手动补充信息。
- 处理包含敏感信息（如 API 密钥、数据库地址、内部接口）的代码时，应提前进行脱敏处理。
- 大型项目建议分模块、分批次生成文档，以获得更精确的输出结果。

## 最佳实践

- 在日常开发中养成编写规范注释的良好习惯，从源头提升文档质量。
- 将本技能集成到 CI/CD 流程中，实现代码变更后文档的自动更新与部署。
- 定期对生成文档进行复核与版本管理，确保其与代码库保持一致。
- 结合团队的编码规范，统一注释模板，可显著提升文档生成的一致性与可读性。