代码技术文档自动生成器

## 功能概述

代码技术文档自动生成器是一款面向开发团队的智能写作辅助技能，能够解析多种编程语言的源代码文件，自动提取其中的注释、函数签名、参数说明、返回值信息及代码结构，生成结构清晰、内容完整的技术文档。

支持的语言包括但不限于 Python、JavaScript、TypeScript、Java、Go、C/C++ 等。生成的文档符合常见的技术文档规范（如 JSDoc、docstring、GoDoc 等），可直接用于项目 Wiki、API 文档或代码库说明。

## 使用场景

- 新项目接入：快速为遗留代码补全技术文档
- 开源项目维护：自动生成 README 与 API 参考文档
- 团队协作：统一代码注释规范与文档输出格式
- 代码审查：辅助理解函数功能、参数约束与调用逻辑

## 调用步骤

1. **准备代码内容**：将需要生成文档的源代码片段或完整文件内容提供给技能。可一次提交单个文件，也可提交多个文件或整个项目目录。
2. **指定文档类型**：明确告知期望的输出格式，例如 API 参考文档、模块说明文档、函数手册或项目 README。
3. **补充上下文信息**（可选）：若有特定需求，如指定文档语言（中文/英文）、目标读者（开发人员/终端用户）、输出风格（简洁/详尽）等，请一并说明。
4. **提交请求**：触发技能后，系统将自动解析代码并生成对应文档。
5. **审阅与调整**：检查生成内容，根据需要要求技能对特定部分进行修改、补充示例或调整格式。

## 文档结构

生成的文档通常包含以下小节：

- **模块/文件概述**：说明文件用途与核心功能
- **函数/方法列表**：按字母或逻辑顺序排列
- **函数详细说明**：包含函数名、参数列表、返回值、抛出异常、调用示例
- **类与对象**：描述类属性、方法与继承关系
- **依赖关系**：列出外部依赖与引用关系
- **使用示例**：提供典型调用场景的代码片段

## 注意事项

- **注释质量影响输出**：源代码中已有的注释越规范、越详细，生成的文档质量越高。建议在函数顶部添加简洁的功能说明，参数与返回值使用标准的注释标记（如 `@param`、`@return`）。
- **类型推断存在限制**：对于动态类型语言或未声明类型的参数，技能将尝试从上下文与赋值语句中推断类型，但可能存在偏差，请人工核对。
- **敏感信息过滤**：请避免在请求中包含 API 密钥、数据库密码等敏感信息，生成的文档同样不应包含此类内容。
- **大文件处理**：单个文件超过 5000 行时，建议拆分为多个请求以获得更精准的输出。
- **版本一致性**：若同一函数存在多个版本或分支，请在请求中注明对应的代码版本，确保文档与实际代码一致。
- **二次校对建议**：自动生成的文档建议由开发人员进行最终校对，特别是业务逻辑、边界条件与异常处理部分。

## 最佳实践

- 在提交代码前，先运行代码格式化工具，确保缩进与风格统一
- 提供项目的简要说明（如 README 摘要），帮助技能更好地理解代码上下文
- 对于复杂业务逻辑，可附带关键流程的伪代码或文字说明
- 批量生成时，按模块或目录分组提交，提升处理效率