用途
inline-documentation 是一个用于编写代码时补充文档的技能。它的出发点很直接：假设文档会从代码中自动生成，因此写代码时就把文档写完整。其核心原则是——未来的开发者（也包括你自己）会阅读这段代码，请帮助他们。
该技能在使用时会进行声明：我正在为这段代码添加完整的行内文档。
主要能力
需要文档化的内容
- 公共函数/方法：完整的 JSDoc/docstring。
- 公共类：类级别文档。
- 公共接口/类型：用途说明。
- 导出的常量：它们控制什么。
- 复杂逻辑：解释“为什么”，而不是“做什么”。
- 非显而易见的决策：解释推理过程。
可以跳过的内容
- 私有琐碎辅助函数：本身已自明。
- 单行 getter：从名称即可看出。
- 标准模式：众所周知的惯用法。
- 测试文件：测试本身就是文档。
使用方式
TypeScript/JavaScript（JSDoc）
函数文档示例中包含：简要描述、@description 详细说明、@param 参数（含类型语义，如税率为小数 0.08 表示 8%）、@returns 返回值、@throws 异常、@example 示例。
类文档示例中包含：类职责说明、@description 实现方式（如使用 JWT 做无状态认证并用 Redis 跟踪会话失效）、@example 用法；构造函数与方法各自也有 @param、@returns、@throws 等标注。
接口文档示例中，每个属性都有说明，并注明默认值与取值范围（如 'memory' | 'redis'），必填条件也会标注。
Python（Docstrings）
函数 docstring 使用 Args、Returns、Raises、Example 等段式说明；类 docstring 使用 Attributes 与 Example；构造函数同样有 Args 说明。
行内注释
- 复杂算法处可说明选择原因，例如使用优先队列以获得 O(E log V) 复杂度，而不是线性搜索 O(V²)。
- 应解释“为什么”而非“做什么”：例如“重试计数从 1 开始，因为初次尝试不计入”，而不是“计数器加 1”。
- 可链接上下文：例如引用 RFC 7519 说明 JWT 过期时间是自 epoch 起的秒数，或引用 issue #234 说明为何不能使用更简单的方案。
- 标记非显而易见的行为：例如 IMPORTANT 标注顺序很重要（认证必须在限流之前运行），WARNING 标注会原地修改输入数组。
适用场景
该技能会在以下流程中被应用：issue-driven-development 的第 7 步，以及 comprehensive-review 的文档标准检查。它旨在保障代码可维护性、便于新人上手、提升生成文档质量，并增强 API 的可发现性。
文档检查清单
- 函数/方法：简要描述、详细描述（复杂时）、所有参数、返回值、异常、示例（用法不明显时）。
- 类：类用途、使用示例、所有公共方法、公共属性。
- 接口/类型：用途、每个属性、有效取值（枚举/联合类型）。
反模式与正确做法
- 没有文档 → 为所有公共 API 写文档。
- 文档过期 → 随代码变更同步更新文档。
- 显而易见的注释 → 只记录非显而易见的内容。
- 缺少示例 → 为复杂 API 添加示例。
- 复制粘贴的文档 → 编写针对性的文档。
生成文档
- TypeScript：使用 TypeDoc（npx typedoc src/index.ts --out docs）或 TSDoc（npx @microsoft/api-extractor run）。
- Python：使用 Sphinx（sphinx-apidoc -o docs/source src/ 与 sphinx-build docs/source docs/build）或 pdoc（pdoc --html src/ -o docs/）。
限制
资料未提供该技能的具体安装命令、支持的平台范围、收费或价格信息，以及除上述集成流程外的其它约束，这些内容暂未提供。