源代码技术文档生成器

# 源代码技术文档生成器

## 技能简介

本技能能够自动分析源代码中的注释、函数签名以及代码结构，生成符合规范的技术文档。无论是 API 文档、类说明还是使用指南，都能快速生成完整的文档内容。

## 适用场景

- 为开源项目生成完整的技术文档
- 为内部代码库编写 API 说明文档
- 为新模块或函数生成使用指南
- 将代码注释转换为标准格式文档
- 为团队统一代码文档风格

## 调用步骤

### 第一步：准备源代码

将需要生成文档的源代码复制到对话中。确保代码包含完整的注释内容，包括：

- 文件顶部的版权和说明注释
- 类和函数的 JSDoc/文档注释
- 关键代码段的行内注释
- 函数参数和返回值的说明

### 第二步：指定文档格式

根据需求指定输出格式，常见格式包括：

- Markdown（.md）
- HTML
- reStructuredText（.rst）
- Javadoc 风格
- OpenAPI/Swagger 规范

### 第三步：执行文档生成

使用触发指令调用本技能：

```
请为以下代码生成技术文档
```

随后将源代码粘贴在指令下方。

### 第四步：审阅与调整

生成的文档会包含以下部分：

- 模块/类概述
- 方法/函数说明
- 参数详解
- 返回值说明
- 使用示例代码
- 注意事项和警告

请仔细审阅生成内容，根据实际需求进行适当调整。

## 支持的编程语言

本技能支持以下主流编程语言的文档生成：

- JavaScript / TypeScript
- Python
- Java
- C / C++
- C#
- Go
- Rust
- PHP
- Ruby
- Swift
- Kotlin

## 注意事项

1. **注释完整性**：源代码中的注释越详细，生成的文档质量越高。建议在编写代码时遵循良好的注释规范。

2. **文档维护**：生成的文档应定期更新，确保与代码版本保持一致。

3. **敏感信息处理**：如代码包含敏感信息（如密钥、密码），请在生成文档前进行脱敏处理。

4. **格式兼容性**：不同项目可能使用不同的文档规范，生成后请根据项目要求进行调整。

5. **示例代码验证**：生成的使用示例代码建议在实际环境中测试验证，确保准确性。

6. **多语言混用**：如项目包含多语言代码，请分批处理，每种语言单独生成文档。

7. **编码格式**：确保源代码文件使用 UTF-8 编码，避免文档中出现乱码。

## 最佳实践

- 在函数上方使用标准化的文档注释格式
- 为每个公共 API 提供使用示例
- 在文档中明确标注版本信息和变更历史
- 使用清晰的命名和注释风格
- 定期根据代码变更更新文档内容