tsdoc

tsdoc — SKILL.md

**变体：**标准 · **使用时机：**调用此技能并将其应用于 TypeScript 文件或接口后，它会返回已添加文档的代码或约定决策；随后控制权交还调用方。

概述

TSDoc 是 Microsoft 为 TypeScript 文档注释制定的标准语法，即紧接在声明之前的 /** ... */ 块。该标准固定了一组标签和一个解析器（@microsoft/tsdoc），使 TypeDoc、API Extractor、编辑器 IntelliSense 等独立工具都能对注释结构达成一致。此技能规定了编写这些注释的约定：哪些符号值得添加文档注释、使用哪些 TSDoc 标签以及如何使用，以及将 TSDoc 与传统 JSDoc 区分开来的唯一规则——不要在注释中重复类型，因为 TypeScript 类型本身已经包含这些信息；注释应说明意图和行为。这相当于 TypeScript 中面向公共接口的文档字符串规范（例如 Python 的 Google 风格文档字符串，并使用文档字符串检查工具进行校验）：记录导出的 API 接口，跳过无关内容。

何时启用

• ✅ 为导出/公开的 TypeScript 符号编写文档注释——函数、类、类型/接口、React 组件及其 props、自定义 hook。
• ✅ 为 TS 代码库制定或规范文档注释约定。
• ✅ 判断给定符号要记录哪些内容以及如何记录（使用哪些标签）。
• ✅ 审查/修正现有注释——例如，删除与 TS 类型重复的 JSDoc 风格 {type} 注解，或将 @return 更正为 @returns。

以下情况请勿启用：

• 设置自动生成的文档站点——这是 TypeDoc 的用途；此技能只会提供相关指引（参见注意事项）。
• 构建组件目录/交互式文档——这是 Storybook 的用途，不在范围内（仅提供指引）。
• 检查或格式化通用代码风格——这是项目的 linter/formatter（例如 Biome）的用途；它不会校验文档注释内容。
• 在没有类型系统的纯 JavaScript 中标注类型——这是 JSDoc-as-types，是另一种实践；此技能明确不适用于这种做法。

工作流

步骤 1：判断是否要为该符号添加文档注释

记录模块使用者会用到的公开/导出 API 接口。其余内容跳过。最有价值的是做出判断，而不是罗列标签。

记录：

• 导出的函数、类和方法，只要其行为无法从名称和签名中完全看出。
• 导出的类型和接口——尤其是 React 组件的 props 接口（为每个不明显的字段添加一行说明）。
• 导出的 React 组件和自定义 hook——说明其渲染/返回内容，以及任何不明显的参数或选项。

跳过（不要记录）：

• 不属于使用者所用接口的私有/内部符号。对于因工具需要而导出、但不面向第三方的符号，应使用 @internal 修饰符标记，而不要将其作为公开符号记录。
• 机器生成的代码——例如 OpenAPI/openapi-ts 客户端、代码生成工具的输出。生成的注释（或缺少的注释）由生成器负责；不要手动编写覆盖它们。
• 名称和类型已能说明一切的简单、显而易见的单行内容（isEnabled: boolean、透传 getter）。
• 仅仅复述类型的文字（参见步骤 3——首要规则）。

步骤 2：编写摘要，然后在 @remarks 中补充细节

第一段——即第一个块标签之前的所有内容——就是摘要。保持简短：文档站点会在 API 索引列表中显示摘要。以简洁的句子说明该符号的作用。

将较长的讨论（注意事项、设计说明、背景、相关 API 的链接）放入 @remarks 块中。@remarks 会结束摘要并开始详细说明部分；其中不应重复摘要内容。

/**
 * Returns the arithmetic mean of two numbers.
 *
 * @remarks
 * Both inputs are treated as finite; passing `NaN` propagates `NaN`.
 * For a list of values, use {@link average} instead.
 *
 * @param x - The first input number
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 *
 * @example
 * Basic usage:
 *
 *     mean(2, 4); // 3
 */
export function mean(x: number, y: number): number {
  return (x + y) / 2;
}

第 3 步：记录意图，而非类型（TSDoc 与 JSDoc）

首要规则。过去，JSDoc 会在注释中标注类型，因为纯 JavaScript 没有类型（@param {string} name）。TypeScript 已在代码中声明类型，因此 TSDoc 标签不带 {type}——TSDoc 的 @param 只需写成 @param name - description。记录原因、方式和含义，而非类型是什么。

// ANTI-PATTERN — JSDoc-style type annotation, redundant with the TS signature
/**
 * @param {string} userId  the user id
 * @param {number} limit   the limit
 * @returns {Promise<User[]>}
 */

// CORRECT — TSDoc: hyphen syntax, no types, documents intent
/**
 * Fetches the most recent users created by `userId`'s organization.
 *
 * @param userId - Owner whose organization is queried
 * @param limit - Maximum rows to return; the server caps this at 100
 * @returns The users, newest first
 */
export async function recentUsers(userId: string, limit: number): Promise<User[]> { /* ... */ }

注意，规范要求 @param name - description 中的连字符；省略它会被 TSDoc 解析器标记。

第 4 步：使用合适的标签

使用 references/tag-taxonomy.md 中按类别划分的标签体系（块级、行内、修饰符——需要查看每个标签的完整详情时再加载）。日常常用的子集：

• @param name - desc、@returns desc——用于函数输入和输出，在含义不明显时使用。
• @typeParam T - desc——用于泛型类型参数（连字符语法与 @param 相同）。
• @remarks——用于摘要之外的详细说明。
• @example——用于用法示例；第一行会被视为示例标题。
• @defaultValue——用于类／接口字段或属性的默认值。
• @throws——每种调用方需要了解的异常类型各写一个块。
• @see——用于交叉引用；@deprecated <message>——标记弃用，并指出替代项。
• {@link Target | label}、{@inheritDoc}——用于行内交叉引用／继承基类成员的文档。
• @public / @internal / @beta / @alpha——用于控制公开发行内容的发布阶段修饰符。

第 5 步：强制检查——默认仅靠约定

检查代码的代码检查器／格式化工具（例如 Biome）不会验证文档注释的内容——它没有 TSDoc 合规性规则。因此，默认做法是仅靠约定：本技能即为标准；无需额外工具，也无需第二个代码检查器。

如果项目希望在 CI 中以机械方式验证 TSDoc 语法，官方工具是 eslint-plugin-tsdoc（单条规则 tsdoc/syntax）。配置片段和明确的权衡说明见 references/enforcement.md——它需要 ESLint，因此在已有快速代码检查器的情况下采用它，会重新引入 ESLint，形成双代码检查器的局面；而采用单代码检查器方案，正是为了避免这种情况。将其视为可选的 CI 参考，而非默认做法。

规则

硬性规则（绝不违反）：

• 注释中不写类型。 TSDoc 标签绝不带 {type}。TS 签名是类型的唯一事实来源；注释用于说明意图／行为。绝不要建议或在 .ts／.tsx 文件中编写 JSDoc 风格的 {type} 注解。
• 记录公共 API，跳过其余内容。 导出／被使用的符号在行为不明显时应添加注释。私有／内部符号、生成代码和简单明了的情况不添加注释。
• 正确分类标签。 块级标签用于引入一个段落（位于行首）；修饰符标签是无内容的独立标记；行内标签以 {@...} 形式出现在文本中。不要创造非标准标签——解析器会对无法识别的标签发出警告。
• @param／@typeParam 使用连字符：@param name - description。使用 @returns，而不是 @return。
• 摘要保持简短；详情放在 @remarks 中。 不要把所有内容都塞进摘要段落。

偏好（可覆盖）：

• 默认采用仅靠约定的强制检查；只有在明确需要进行 CI 语法验证且接受增加第二个代码检查器的成本时，才添加 eslint-plugin-tsdoc。
• 优先记录不明显的行为／边界情况，而不是重述显而易见的签名。
• 使用 {@link} 关联相关 API，而不是重复其说明。

注意事项

• 代码检查器／格式化工具不会检查文档注释。 Biome 这类工具会检查／格式化代码；它们对文档注释涉及最接近的功能是星号格式规则（useSingleJsDocAsterisk），以及追踪 {@link} 引用以检查未使用的导入——两者都不会验证 TSDoc 规范性。不要以为“检查通过”就意味着文档注释正确；这属于约定或 eslint-plugin-tsdoc 的范畴。
• @deprecated 是块标签，不是修饰符。 根据规范，它后面应有一句话，指出推荐的替代方案（@deprecated Use {@link newFn} instead.）——它不是像 @internal 那样不带内容的标记。将其归类为修饰符是常见错误。
• @return 与 @returns。 TSDoc 标准规定使用 @returns。@return 是常见的 JSDoc 惯性误用，解析器会对此发出警告。
• 忘记 @param 后的连字符。 @param x The value 格式不正确；必须写成 @param x - The value。TSDoc 解析器会发出连字符警告。
• {@inheritDoc} 不应与摘要和 @remarks 同时出现。 注释使用 {@inheritDoc} 时，不得同时声明自己的摘要或 @remarks 部分——这些内容会被继承。
• @override 与 TS 关键字。 在源代码中优先使用 TypeScript 的 override 关键字；只有在文档根据 .d.ts 声明文件生成时，才使用 @override 修饰符标签。
• TypeDoc 是使用者，不是编写者。 TSDoc 注释是 TypeDoc 读取并生成 API 网站的输入。生成该网站是单独的、超出范围的工作——本技能只编写 TypeDoc 之后会读取的注释。不要把 TypeDoc 配置纳入文档注释任务。

反模式

• “TypeScript 已经有类型了，但为了清晰，我会用文字再描述一遍。” 不要这样做——@param userId - The user ID string 只是重复描述类型，没有增加任何信息。应记录原因／方式，或者省略该标签。
• “为了完整，每个符号都应该有文档注释。” 不要这样做——为简单的 getter、显而易见的参数和一目了然的单行代码编写文档，只会制造噪声，掩盖真正重要的注释。
• “我也来改进生成客户端中的注释。” 不要这样做——机器生成的代码由生成器负责；手动修改会被覆盖，也不应投入文档编写精力。
• “我会添加 eslint-plugin-tsdoc，以防万一。” 默认不要这样做——它会让 ESLint 重返使用单一快速检查器的项目。默认采用约定；只有在明确决定接受第二个检查器时，才引入该插件。
• “我来发明一个 @usage／@note 标签。” 不要这样做——非标准标签会触发解析器警告，并破坏工具互操作性。使用标准标签集（@remarks、@example、@see）。

输出

编写正确、符合规范的 TSDoc 文档注释，以说明 TypeScript 公共接口——在适当情况下包含摘要以及 @param／@returns／@remarks／@example（和修饰符／内联标签）；不为私有／内部／生成／简单的符号编写文档，并且不用文字重复描述类型。或者，明确说明文档注释约定决策（上述规范，以及选择仅采用约定还是通过 eslint-plugin-tsdoc 强制执行）。后续审查者或调用此工作流的对象是使用者；这些注释也会用于编辑器 IntelliSense，以及（如果项目以后添加）TypeDoc 网站。

相关内容

• references/tag-taxonomy.md — 完整的块标签／内联标签／修饰符标签表（需要日常子集之外的标签时加载）。
• references/enforcement.md — eslint-plugin-tsdoc 配置片段与第二个检查器的权衡；TypeDoc／Storybook 相关指引。
• references/sources.md — 研究来源。
• JS/TS 检查器和格式化工具技能（例如 Biome 技能）——代码质量检查环节不会验证文档注释内容；本技能提供互补的文档注释约定。
• TypeScript 类型检查技能——类型本身就能说明自身，这正是本技能要求不要用文字重复描述类型的原因。

渐进式披露

• references/tag-taxonomy.md — 块级 / 行内 / 修饰符标签参考，包含各标签的分类和语法。**在以下情况加载：**在日常子集中使用某个标签之外的标签，或核实标签类别时。
• references/enforcement.md — eslint-plugin-tsdoc 配置及其权衡，以及 TypeDoc / Storybook 的范围外说明。**在以下情况加载：**决定采用何种强制执行工具，或有人询问文档站点生成时。
• references/sources.md — 引用来源。**在以下情况加载：**审查来源依据时。

正文长度限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个 token — 每轮都会保留在上下文中。
• 每个参考文件：超过 10k 个 token 时警告，超过 25k 个 token 时错误。参考文件总计：超过 25k 个 token 时警告，超过 50k 个 token 时错误。