代码文档智能生成助手

# 代码文档智能生成助手

## 技能简介

本技能是一个基于大语言模型的智能工具，专门用于自动将源代码中的注释、函数签名、参数说明等信息转换为结构化的技术文档。它能够理解代码的语义和结构，生成符合行业规范的API文档、使用说明、开发指南等内容，极大地提升开发者的文档编写效率。

## 核心功能

- **智能代码解析**：自动识别代码注释、函数签名、参数说明等关键信息
- **多语言支持**：支持Python、JavaScript、Java、Go、TypeScript、C++等主流编程语言
- **规范文档生成**：输出符合业界标准的Markdown格式技术文档
- **语义理解**：深入理解代码逻辑和业务意图，生成准确的功能描述
- **示例代码生成**：自动生成函数调用示例和使用代码片段
- **批量处理**：支持一次性处理多个函数或整个模块的文档生成

## 适用场景

- 开源项目编写README文档和API参考手册
- 企业内部技术文档的快速生成与维护
- 遗留代码（Legacy Code）的文档补充工作
- 团队内部知识库建设与共享
- 自动化开发流程中的文档环节
- 技术博客和教程的代码说明部分

## 调用步骤

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

将需要生成文档的代码片段整理好，确保代码包含：
- 完整的函数或类定义
- 必要的注释说明（行注释或块注释）
- 参数类型标注（如有）
- 返回值说明（如有）

```python
def calculate_statistics(data: list, method: str = "mean") -> dict:
    """
    计算数据集的统计指标
    
    Args:
        data: 输入的数值列表
        method: 统计方法，可选值包括 mean, median, mode
        
    Returns:
        包含统计结果的字典，包含 value 和 count 字段
    """
    pass
```

### 第二步：明确文档需求

根据实际需要确定以下要素：
- **文档类型**：API文档、用户手册、开发指南还是代码注释增强
- **详细程度**：简要概述还是完整说明
- **输出格式**：纯Markdown还是包含代码块的完整文档
- **语言偏好**：中文文档还是英文文档

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

使用自然语言向AI助手提交请求，清晰说明：
- 需要处理的代码内容
- 期望的文档类型和风格
- 特殊格式要求（如有）

### 第四步：审阅与优化

检查生成文档的：
- 技术准确性：参数说明是否符合代码实际
- 表达清晰度：描述是否易于理解
- 完整性：是否遗漏重要信息
- 格式规范性：是否符合项目文档规范

如有需要，可进行迭代优化。

## 注意事项

- **准确性验证**：生成的文档内容必须经过人工审核，确保技术描述准确无误
- **信息安全**：避免将包含敏感信息的代码直接用于文档生成，如数据库密码、API密钥等
- **上下文补充**：对于复杂的业务逻辑，建议补充额外的上下文说明以提高文档质量
- **格式一致性**：生成的文档风格应与项目现有文档保持一致
- **示例代码测试**：自动生成的代码示例需要实际运行验证，避免出现语法错误
- **定期更新**：代码变更后应及时更新对应文档，保持文档与代码的同步
- **知识边界**：对于极其专业或领域特定的术语，AI可能无法完全准确理解，建议专家审核

## 输出示例

```markdown
# 函数名：calculate_statistics

## 功能描述
计算给定数据集的统计指标，支持多种统计方法。

## 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| data | list | 是 | - | 输入的数值列表 |
| method | str | 否 | "mean" | 统计方法，支持 mean/median/mode |

## 返回值

| 字段 | 类型 | 说明 |
|------|------|------|
| value | number | 统计结果值 |
| count | int | 有效数据数量 |

## 使用示例

```python
result = calculate_statistics([1, 2, 3, 4, 5], method="mean")
print(result)  # {'value': 3.0, 'count': 5}
```

## 注意事项
- data 参数不能为空列表
- method 参数仅支持预设的三种统计方法
```

---

**使用提示**：为获得最佳文档生成效果，请在代码中添加清晰、规范的注释，并明确说明参数类型和返回值预期。