用途:在写代码时同步补齐完整的内联文档,假设文档会由代码自动生成,从而提升可维护性与上手效率。使用时需声明:“I'm adding complete inline documentation for this code.”
主要能力:为公共函数/方法写完整 JSDoc 或 docstring;为公共类写类级文档;为公共接口/类型说明用途;为导出常量说明其控制内容;为复杂逻辑解释“为什么”而非“做什么”;为非显然决策说明理由。TypeScript/JavaScript 采用 JSDoc,Python 采用 docstring,均覆盖参数、返回值、异常和示例。接口文档需逐属性说明并标注有效取值。
使用方式:按检查清单逐项核对公共元素。函数/方法需有简述、详细描述(如复杂)、全部参数、返回值、异常、示例(如用法非显然);类需有用途、用法示例、公共方法与属性文档;接口/类型需有用途、各属性说明及枚举/联合类型有效值。行内注释用于复杂算法、链接上下文(如 RFC、issue)、标记非显然行为(IMPORTANT、WARNING),并解释原因。
可跳过:私有且显而易见的辅助函数、单行 getter、标准模式、测试文件(测试即文档)。反模式包括不写文档、文档过时、注释显而易见内容、缺少示例、复制粘贴文档,应改为记录所有公共 API、随代码更新文档、只记录非显然内容、为复杂 API 加示例、写具体文档。
生成文档的示例命令:TypeDoc 为 npx typedoc src/index.ts --out docs;TSDoc 为 npx @microsoft/api-extractor run;Sphinx 为 sphinx-apidoc -o docs/source src/ 与 sphinx-build docs/source docs/build;pdoc 为 pdoc --html src/ -o docs/。该技能被 issue-driven-development 第 7 步和 comprehensive-review 的文档标准引用。限制:资料未提供安装命令、收费、价格、平台或效果信息。