jsdoc

JSDoc

仅在谨慎的读者无法单凭名称和类型推断意图、约束或失败模式时添加 JSDoc。优先用 TypeScript 类型表达结构；用 JSDoc 说明原因、时机和可能出问题的地方。

何时编写文档

符合以下任一条件时，记录该符号：

• 控制流、算法或状态机乍看之下并不明显。
• 行为依赖不变量、顺序、时序、幂等性或并发。
• 副作用很重要（I/O、变更、缓存、网络、计时器、全局状态）。
• 失败模式、抛出错误、空结果或部分成功属于契约的一部分。
• 单位、范围、格式或领域含义无法从类型中明确得知。
• 公共 / 导出 API 的调用者会在不阅读实现的情况下使用它。
• 存在弃用、迁移、安全或兼容性约束。

何时不编写文档

符合以下情况时，跳过 JSDoc：

• 名称和 TypeScript 类型已经说明了该符号的含义。
• 函数体只是简单的 getter、setter、直通封装或单行 map/filter。
• 注释只是重述参数或返回类型。
• 注释只是叙述下一行做了什么（// increment i）。
• 代码为生成代码、自描述的测试 fixture 或 vendored 文件（记录公共测试辅助工具的情况除外）。

默认：不添加注释。不写胜过写了却添乱。

TypeScript 规则

1. 类型表达结构。 当签名中已有 id: string 时，不要在 JSDoc 中重复类型（@param {string} id）。
2. JSDoc 表达含义。 使用说明文字和有选择的标签来描述类型无法表达的行为。
3. 为 TypeScript 编写文档时，优先使用不带类型花括号的 @param name / @returns 说明。
4. 首句应概括行为或用途，而不是重述符号名称。
5. 为不明显的泛型添加简短说明，解释 T 表示什么，以及类型界限之外的任何约束。
6. 对重载，分别记录每种不同的调用方式；共享的注意事项写在实现或主要导出项上。
7. 遵循项目现有的 JSDoc 风格（标签集合、标点、使用 @returns 还是 @return），前提是项目已有主流风格。

已记录符号必须包含的内容

每个新增的 JSDoc 块都必须包含：

1. 摘要 — 用一句话说明它的作用或存在的原因（避免“此函数……”之类的赘述）。
2. 不明显的细节 — 仅说明读者容易忽略的内容：不变量、顺序、副作用、边缘情况、单位、安全性。

仅在确有必要时添加标签：

标签	使用场景
@param	参数语义、单位、有效范围，或类型之外的“必须……”约束
@returns	返回值含义、空值 / 哨兵情况，或“永不返回”一类的契约
@throws	调用者应处理的已记录错误条件
@example	类型本身无法说明的非平凡用法（保持简短；通常一个示例足够）
@see	相关符号、RFC、工单或算法来源
@deprecated	替代方案和计划移除的意图
@template	仅用于 JS 文件，或说明泛型的作用；在 .ts 文件中优先使用 TypeScript 类型参数

不要杜撰项目从未使用过的标签。优先使用标准的 JSDoc / TypeScript 支持的标签。

工作流程

1. 确定范围 — 按用户指定的文件、符号或“仅公共 API”执行。若范围不明确，优先处理导出项和复杂符号，而非私有辅助函数。
2. 扫描 — 按“何时编写文档”列表查找候选项。跳过显而易见的代码。
3. 审查现有 JSDoc — 删除或改写重述类型、与实际行为不符或叙述显而易见内容的注释。
4. 编写 — 添加简洁的文档块；优先直接编辑符号，而非创建单独的文档文件。
5. 验证 — 重新阅读：新队友是否无需逐个打开被调用项，就能理解难点？类型是否仍与说明一致？

质量标准

好的 JSDoc：

• 说明从函数签名中看不出来的约束或故障模式。
• 即使实现细节在同一契约下发生变化，内容仍然准确。
• 在可能的情况下，篇幅短于所说明的代码。

不好的 JSDoc：

• @param id - The id
• 函数签名已说明返回类型，却又写 @returns {Promise<User>}
• 复述函数体的长篇说明
• 与代码矛盾的过时注释（删除或修正；绝不保留误导性文档）

示例

具体的好坏模式：examples.md。

完成情况

收到文档编写范围的请求时，请简要说明：

• 编写了哪些文档，以及它们符合要求的原因。
• 哪些内容未编写文档（并说明这是有意为之）。
• 删除了哪些冗余 JSDoc，或修正了哪些错误的 JSDoc。