智能技术文档生成器

# 智能技术文档生成器

## 技能概述

智能技术文档生成器是一款基于人工智能的代码文档自动生成工具。当用户需要为源代码生成专业文档时，此技能会自动分析代码结构、注释内容和函数签名，输出结构清晰、内容完整的技术文档。该技能支持主流编程语言的代码解析，能够帮助开发者显著提升文档编写效率，确保代码文档的及时更新与一致性。

## 核心功能

### 1. 智能代码解析

技能能够自动识别代码中的以下元素：

- 函数和方法的定义、参数、返回值
- 类和接口的结构
- 变量和常量的用途说明
- 代码块的功能描述
- 导入模块和依赖关系

### 2. 多语言支持

当前支持的编程语言包括：

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

### 3. 文档格式输出

生成文档支持以下格式：

- Markdown 格式（默认）
- API 参考文档
- 使用示例代码
- 变更日志条目

## 调用步骤

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

将需要生成文档的源代码整理好，确保代码中包含必要的注释和文档字符串。建议使用标准的注释规范，如 JSDoc、Docstring、JavaDoc 等格式，这有助于生成更准确的文档内容。

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

在调用技能时，请明确以下信息：

- 目标文档类型（API文档、使用指南、代码说明等）
- 期望的详细程度（简要概述或详细说明）
- 特定的语言偏好或格式要求

### 第三步：提交代码并生成

将源代码提交给技能，等待系统分析并生成文档。生成完成后，系统会返回完整的 Markdown 格式文档内容。

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

建议用户对生成的文档进行审阅，根据实际需求进行必要的修改和补充，以确保文档的准确性和完整性。

## 使用示例

**触发方式**：当用户发送类似「为这段代码生成文档」、「帮我写 API 文档」、「给代码添加说明」等请求时。

**示例输入**：用户提供一段包含注释的源代码

**示例输出**：

```markdown
# 函数名：calculateSum

## 描述
计算给定数组中所有元素的和。

## 参数
- `numbers` (number[]): 数字数组

## 返回值
(number): 数组元素的总和

## 使用示例
```javascript
const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // 输出: 15
```
```

## 注意事项

1. **代码质量依赖**：生成的文档质量很大程度上取决于源代码中的注释质量。建议在代码中添加清晰、规范的注释，这将显著提升文档生成效果。

2. **上下文补充**：对于复杂的业务逻辑或特殊实现细节，建议在请求时补充额外的上下文说明，帮助技能更准确地理解代码意图。

3. **安全审查**：涉及敏感信息的代码（如密钥、密码、认证凭据等），请在提交前进行脱敏处理，切勿将包含敏感信息的代码直接用于文档生成。

4. **结果校验**：自动生成的文档可能存在理解偏差，请务必对生成结果进行人工审核，确保文档内容与实际代码行为一致。

5. **版本同步**：当代码发生变更时，建议及时重新生成相关文档，以保持文档与代码的同步更新。

6. **复杂项目**：对于大型项目或复杂模块，建议分批提交代码进行文档生成，以获得更好的效果。

## 适用场景

- 新项目启动时的快速文档搭建
- 开源项目的 README 和 API 文档编写
- 代码审查前的文档准备
- 技术分享和培训材料的准备
- 老旧代码的文档补全工作