代码自动生成文档

要解决的问题

函数级注释缺失、API 文档长期不更新是常态。手写文档既耗时又容易与代码脱节——签名改了，三个月前写的参数说明还挂在那里。现有工具要么只覆盖单一语言，要么生成的文本只是复述签名，看不到设计意图和约束条件。

核心能力与工作流程

这个 Skill 把「读代码 → 定范围 → 写文档 → 校验」串成一条可审查的流程：

• 盘点代码库：遍历项目树，列出公开模块、类、函数、常量和类型定义，标记哪些符号已有文档、哪些缺失或过期
• 确定文档范围：按请求生成内联注释、独立 API 参考或项目级 README.md，并匹配项目已有的格式约定（Google-style、JSDoc、Javadoc、Godoc 等）
• 分析签名与行为：检查参数类型、返回值、默认值、抛出的异常和副作用；有测试文件时阅读测试来理解预期用法与边界情况
• 生成并写入：每个公开 API 至少附带一个使用示例，支持原地插入 docstring 或更新 docs/ 目录下的 Markdown 文件
• 校验交叉引用：核对参数名与实际签名是否一致、引用的类型是否存在、示例代码是否语法有效，不一致处会标记出来供人工复查

覆盖的格式包括 Python（Google-style / NumPy-style / Sphinx reStructuredText）、JavaScript 与 TypeScript（JSDoc / TypeDoc 注释）、Java（Javadoc）、Go（声明上方的注释块）、Rust（/// 文档注释与 #[doc] 属性）、Ruby（YARD），以及 Markdown 层的 README、CHANGELOG 和 ADR。

适用边界与注意点

• 运行时动态生成的 API（装饰器注册的路由、插件系统注册的方法）静态分析可能漏掉，Skill 会提醒改用运行时内省或手动补注
• 项目文档约定不明确时会先询问再决定风格，不会中途切换造成混杂
• 涉及发送、发布、上传、删除等外部写入动作前必须先取得明确确认，默认只交付分析、草稿和建议
• 私有内部实现默认不写文档，避免引导使用者依赖不稳定的接口
• 代码变更后文档可能过期，建议在 CI 阶段做文档与签名的一致性校验
• 包含内部 URL、凭据或业务逻辑细节的文档，对外发布前需要先脱敏