智能代码文档生成助手

## 技能简介

智能代码文档生成助手是一款基于人工智能的文档自动化工具，能够深度解析源代码中的注释、函数签名、类定义及变量命名，自动生成符合行业规范的完整技术文档。该技能支持多种主流编程语言，包括但不限于 Python、Java、JavaScript、TypeScript、C++、Go、Rust 等，可输出 Markdown、HTML、Javadoc 风格、Sphinx 格式等多种文档格式。

## 适用场景

- **新项目初始化**：为新启动的项目快速生成完整的 API 文档框架
- **遗留代码维护**：为缺乏文档的历史代码补充规范的技术说明
- **代码审查准备**：在提交代码审查前自动生成文档，提升审查效率
- **知识库建设**：将分散的代码注释整合为统一的项目文档体系
- **开源项目发布**：为开源项目生成专业的使用文档和 API 参考手册
- **团队知识传承**：帮助新成员快速理解现有代码库的结构和用法

## 调用步骤

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

将需要生成文档的源代码文件准备好，确保代码中包含必要的注释。推荐使用以下注释风格以获得最佳效果：

- Python：推荐使用 docstring（Google 风格、NumPy 风格或 Sphinx 风格）
- Java/JavaScript：使用 JSDoc 或 Javadoc 格式注释
- TypeScript：利用 TSDoc 规范注释

### 第二步：调用技能

用户可通过以下方式触发技能：

1. 直接粘贴代码片段或上传源代码文件
2. 明确指定期望的文档格式（Markdown/HTML/JSON）
3. 说明文档的详细程度（简要/标准/详尽）

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

生成的文档会自动呈现，用户可根据需要进行：

- 检查文档内容的准确性
- 补充或修正自动生成的内容
- 调整文档结构和格式
- 要求重新生成特定部分

### 第四步：导出与应用

确认文档内容无误后，可将文档导出为所需格式，或直接嵌入到现有文档系统中。

## 支持的编程语言

| 类别 | 语言 |
|------|------|
| 脚本语言 | Python, Ruby, PHP, Perl |
| 前端语言 | JavaScript, TypeScript |
| 面向对象 | Java, C++, C#, Go, Swift |
| 系统级 | Rust, C, Kotlin |
| 函数式 | Scala, Haskell, Elixir |
| 数据科学 | R, Julia, MATLAB |

## 文档输出格式

- **Markdown**：适用于 GitHub、GitLab 等平台的 README 和 Wiki
- **HTML**：适用于独立的技术文档网站
- **OpenAPI/Swagger**：适用于 RESTful API 文档
- **JSON Schema**：适用于结构化数据描述
- **PDF**：适用于正式的技术白皮书和用户手册

## 注意事项

1. **代码质量依赖**：生成的文档质量高度依赖源代码的注释完整程度和命名规范性。建议在调用前完善关键函数的 docstring 和注释。

2. **敏感信息处理**：请勿将包含密钥、密码、API 凭证或个人隐私信息的代码粘贴到技能中，所有输入内容均视为非敏感数据处理。

3. **大型文件处理**：对于超过 10,000 行的单个文件，建议分批处理或指定特定模块进行文档生成，以获得最佳效果。

4. **复杂逻辑说明**：自动生成的文档主要描述代码的结构和接口，对于复杂的业务逻辑和算法实现，建议手动补充详细的说明文字。

5. **多语言项目**：混合语言项目请明确标注各文件使用的编程语言，以便系统采用最合适的解析策略。

6. **文档更新维护**：生成的文档应与代码保持同步更新，建议在代码变更后重新运行文档生成任务。

7. **版权与归属**：生成的文档版权归使用方所有，系统不会对生成内容主张任何版权权益。

## 示例输入与输出

**示例输入（Python 代码）**：

```python
def calculate_statistics(data: list, include_outliers: bool = False) -> dict:
    """
    计算给定数据集的统计指标
    
    Args:
        data: 数值型数据列表
        include_outliers: 是否包含异常值计算
        
    Returns:
        包含均值、标准差、中位数的字典
    """
    pass
```

**示例输出（Markdown 文档）**：

---

### calculate_statistics

计算给定数据集的统计指标

**参数：**

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| data | list | 是 | - | 数值型数据列表 |
| include_outliers | bool | 否 | False | 是否包含异常值计算 |

**返回值：**

| 类型 | 说明 |
|------|------|
| dict | 包含均值、标准差、中位数的字典 |

---

通过合理使用智能代码文档生成助手，开发团队可以显著提升文档编写效率，将更多精力投入到核心代码开发中，同时确保项目文档的完整性和一致性。