代码文档智能生成器

## 技能简介

代码文档智能生成器是一款专为开发者设计的AI文档工具，能够自动分析源代码中的注释、函数签名、类结构和参数信息，生成结构清晰、内容完整的技术文档。该技能支持Python、JavaScript、TypeScript、Java、Go、C++等主流编程语言，可输出Markdown、HTML或JSON格式的文档。

## 核心功能

- **智能注释解析**：自动识别JSDoc、Docstring、Doxygen等主流文档注释格式
- **函数签名分析**：提取函数名、参数类型、返回值类型和默认值信息
- **代码结构提取**：识别类、模块、接口及其继承关系
- **多语言支持**：覆盖20+编程语言的语法特性
- **格式灵活输出**：支持Markdown、HTML、JSON三种文档格式

## 调用步骤

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

将需要生成文档的源代码整理为纯文本格式，确保代码包含完整的注释和类型标注。建议使用标准的文档注释格式以获得最佳效果。

### 第二步：提交生成请求

将源代码粘贴到对话中，并明确说明需要的文档格式和详细程度。例如：

- "为以下Python代码生成Markdown格式的技术文档"
- "生成JavaScript函数的API参考文档"
- "创建包含使用示例的技术文档"

### 第三步：审查与调整

生成的文档可能需要根据实际需求进行微调，包括：

- 补充业务逻辑说明
- 添加更多使用示例
- 修正技术细节描述
- 调整文档结构和格式

## 输入要求

| 要求类型 | 具体说明 |
|---------|----------|
| 代码完整性 | 建议提交完整的函数或模块代码 |
| 注释质量 | 使用标准文档注释格式可提升生成质量 |
| 类型标注 | 包含类型信息可生成更准确的文档 |
| 代码量限制 | 单次建议不超过2000行代码 |

## 输出格式说明

### Markdown格式

```markdown
# 函数名称

## 描述
函数功能的简要说明

## 参数
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|

## 返回值
返回值类型及含义

## 使用示例
```javascript
// 示例代码
```

## 注意事项
相关限制和注意点
```

### JSON格式

适合程序化处理，包含完整的文档结构和元数据信息。

## 注意事项

1. **代码隐私**：提交前请确保代码不包含敏感信息，如密钥、密码或业务机密
2. **版权确认**：确保对提交代码拥有使用和文档化的权限
3. **质量验证**：AI生成的文档需人工审核技术准确性
4. **格式兼容**：部分特殊语法结构可能无法完美解析
5. **增量更新**：建议使用版本控制管理文档更新
6. **语义补充**：自动生成的文档缺少业务背景说明，需要手动补充

## 最佳实践

- 在代码中添加详细的文档注释后再生成文档
- 对生成的文档进行Code Review确保准确性
- 建立文档模板规范团队文档风格
- 定期同步代码变更与文档更新
- 将文档生成纳入CI/CD流程实现自动化

## 适用场景

- 新项目初始化文档编写
- 遗留代码库文档补全
- 开源项目README和API文档生成
- 团队内部技术文档规范化
- 代码审查和知识传承

## 限制与局限

本技能在以下情况下可能无法达到最佳效果：

- 代码缺少注释和类型标注
- 使用非主流或自定义编程语言
- 代码结构复杂、依赖关系混乱
- 包含大量动态类型和反射特性

如遇上述情况，建议先优化代码注释和结构，再使用本技能生成文档。