技术文档智能生成器

## 功能概述

技术文档智能生成器是一款面向开发者的 AI 写作辅助技能，能够自动解析源代码中的注释信息（如 JSDoc、Docstring、JavaDoc 等）以及函数/方法的签名定义，快速生成符合行业规范的技术文档。该技能可显著降低文档编写的人力成本，让开发者专注于核心业务逻辑，同时保证项目文档的完整性与时效性。

## 适用场景

- **新项目接入**：为遗留代码库或新接手项目快速补齐缺失的 API 文档。
- **开源项目维护**：为 GitHub、Gitee 等平台的开源仓库自动生成 README、API 参考手册。
- **内部知识沉淀**：将团队核心代码转化为标准化文档，便于新人 onboarding。
- **接口对接说明**：为 RESTful API、SDK、类库生成调用方所需的接口说明文档。

## 调用步骤

1. **提供源代码**：将需要生成文档的源代码文件、代码片段或完整工程路径发送给 AI。
2. **指定文档类型**：明确告知需要生成的文档类型（如 API 文档、模块说明、类文档、函数手册等）。
3. **补充上下文信息**（可选）：提供项目背景、技术栈、目标读者等信息，以便生成更精准的内容。
4. **指定输出格式**：选择 Markdown、HTML、reStructuredText、OpenAPI 等目标格式。
5. **审阅与迭代**：根据生成结果提出修改意见，如调整详细程度、补充示例代码、修正术语等。

## 支持的编程语言

- **编译型语言**：Java、C/C++、Go、Rust、C#、Swift。
- **脚本语言**：Python、JavaScript/TypeScript、Ruby、PHP、Shell、Perl。
- **函数式语言**：Scala、Kotlin、Haskell、Elixir。
- **其他**：SQL、HTML/CSS、R、MATLAB 等常用技术栈均可解析。

## 输出文档结构

生成的文档通常包含以下标准模块：

- **概述**：模块或文件的核心功能简介。
- **函数/方法列表**：按字母或逻辑顺序组织的 API 索引。
- **参数说明**：参数名、类型、是否必填、默认值与含义。
- **返回值**：返回类型、可能值与异常情况。
- **异常说明**：可能抛出的错误类型及触发条件。
- **使用示例**：典型调用场景的可运行代码片段。
- **版本与变更记录**：接口的迭代历史（若信息可用）。

## 注意事项

- **注释质量决定输出质量**：源代码中缺少注释或注释不规范时，生成结果可能不完整或存在推测内容，请人工复核关键信息。
- **敏感信息保护**：避免将包含密码、密钥、个人隐私等敏感数据的代码直接传入，建议先进行脱敏处理。
- **版权与合规**：生成文档时请确保拥有源代码的合法使用权，遵守相关开源协议。
- **大文件处理**：对于超大型代码仓库，建议分模块提交，避免单次请求超出上下文限制。
- **术语一致性**：若项目内有专有术语或命名规范，请在提示中明确说明，以保证文档措辞统一。

## 最佳实践

1. 在代码编写阶段即养成良好的注释习惯（如遵循 JSDoc、Google 风格），可大幅提升生成效果。
2. 结合项目的 README、CHANGELOG 等元数据一起提交，可获得更丰富的上下文。
3. 对生成结果进行二次校对，特别是参数类型、边界条件与异常处理部分。
4. 配合版本控制使用，将生成的文档纳入代码仓库统一管理，随代码变更同步更新。
5. 在 CI/CD 流程中集成文档自动生成任务，实现持续文档化（Continuous Documentation）。

## 总结

技术文档智能生成器通过 AI 能力将繁琐的文档编写工作自动化，帮助团队构建清晰、可维护的技术资产。无论是个人开发者还是大型工程团队，都能从中受益，实现"代码即文档"的高效开发范式。