accelint-ts-documentation

代码文档技能

用于改进 JavaScript/TypeScript 文档的综合技能，包括 JSDoc 注释、注释标记和整体注释质量。

何时启用此技能

在任务涉及以下内容时使用此技能：

JSDoc 文档

• 为导出的函数、类型、接口或类添加 JSDoc 注释
• 验证 JSDoc 是否完整（缺少 @param、@returns、@template 标签）
• 确保 JSDoc 的 @example 标签使用正确的代码围栏
• 使用点表示法为带解构的对象参数编写文档

注释质量

• 使用正确的标记（TODO、FIXME、HACK、NOTE、PERF、REVIEW、DEBUG、REMARK）识别并分类注释
• 删除不必要的注释（已注释掉的代码、编辑历史、显而易见的说明）
• 保留重要注释（标记、linter 指令、业务逻辑）
• 改进注释位置（将行尾注释移到代码上方）

文档审计

• 检查代码的文档完整性
• 确保导出的代码有全面的文档
• 验证内部代码是否具备最低要求的文档

何时不要使用此技能

以下情况不要启用：

• 一般代码质量问题（改用 accelint-ts-best-practices）
• 性能优化（改用 accelint-ts-performance）
• 类型安全改进（改用 accelint-ts-best-practices）
• 特定框架的文档（React PropTypes、Vue props 等）

使用方法

1. 根据任务类型加载参考资料

添加/验证 JSDoc 时：

必须：实施前完整阅读 jsdoc.md。 关键内容：@example 代码围栏语法（此处常见错误）、对象参数点表示法、@template 要求、边缘情况。

除非任务明确提及注释标记（TODO、FIXME 等）或注释质量问题，否则不要加载 comments.md。

审计注释质量时：

必须：实施前完整阅读 comments.md。 关键内容：注释标记标准、应删除与应保留的内容、位置规则。

除非任务明确提及 JSDoc 标签（@param、@returns 等）或函数/类型文档，否则不要加载 jsdoc.md。

仅回答问题（不实施更改）或任务属于一般代码质量问题时，不要加载任何参考资料。

2. 专家判断框架

审计前应用以下思考框架：

问题 1：读者是谁？

• API 使用者：缺少实现上下文 → 提供全面的文档
• 团队成员：了解代码库上下文 → 仅记录不言自明的行为
• 未来的自己（6 个月后）：会忘记细微的决策 → 记录理由

问题 2：是晦涩还是复杂？

• 晦涩 = 意图不明确 → 必须记录（例如，cache.invalidate()——为什么？是为了性能还是正确性？）
• 复杂 = 实现精巧 → 添加实现注释，而非 JSDoc

问题 3：维护成本权衡？

• 频繁变更的代码：文档尽量精简（难以保持准确）
• 稳定的 API：提供全面的文档（能够保持准确）
• 内部工具：简短记录（读者数量少 × 使用频率低 = 投入产出比最低）

双层决策规则

应用思考框架后：

这是导出的代码（公共 API）吗？ → 是：必须提供全面的文档

• 所有 @param、@returns、@template、@throws、@example
• 即使内容“显而易见”也要记录——使用者缺少你的上下文

这是内部代码吗？ → 自行判断：记录无法从以下内容中不言自明的部分：

1. 函数名称和类型签名
2. 参数名称和类型
3. 代码库中的标准模式

经验法则：如果有能力的团队成员会问“为什么？”或“边缘情况是什么？”，就记录下来。如果他们会说“显而易见”，就略过。

3. 评估文档是否充分

使用此决策树判断文档是否完整：

步骤 1：确定可见性层级

Is it exported (public API)?
  YES → Tier 1: Comprehensive documentation required
  NO  → Tier 2: Judgment-based minimal documentation

步骤 2：应用特定实体的要求

第 1 层（导出）——始终必需：

• 描述（用途、使用场景，以及适用实体的“何时使用”）
• 对象的所有 @param 及其属性文档
• @returns（void 除外）
• 泛型的 @template 及约束说明
• @throws 及其触发条件
• 至少一个贴近实际的 @example

第 2 层（内部）——酌情决定：

• 简短描述（一行即可）
• 仅为不明显的参数添加 @param
• 仅在返回值不明显时添加 @returns
• 为泛型添加 @template
• 仅在行为复杂时添加 @example

特定实体的补充要求：

• 类（第 1 层）：构造函数文档、公共方法文档、实例化示例
• 类型/接口（第 1 层）：为所有公共属性添加说明
• 常量/变量：适用时注明单位/约束（例如，“毫秒”“必须为正数”）

充分性检查清单：

将文档标记为“充分”之前，请确认：

• 所有导出项都有完整的文档
• 所有 @param 标签都说明参数的作用（而不只是类型信息）
• 所有 @returns 标签都说明不同情况下会返回什么
• 所有 @example 标签都使用带语言标识符的正确代码围栏
• void 函数没有 @returns
• 泛型函数的每个类型参数都有对应的 @template
• 对象参数使用点表示法记录属性
• 描述侧重于是什么/为什么，而不是如何实现

4. 参考资料不足时

如果遇到参考资料或标准模式未涵盖的情形：

回退策略：

1. 以两层规则（导出 vs 内部）为基础
2. 优先保证清晰，而非面面俱到——记录已知内容也好过猜测语法
3. 使用 TypeScript/JSDoc 官方文档中的标准 JSDoc 约定
4. 使用 NOTE 标记说明不确定之处：// NOTE: JSDoc syntax may need review for [specific case]
5. 如果确实存在歧义，请向用户寻求澄清，而不是自行假设

常见的未涵盖情形：

• 特殊的 TypeScript 功能（映射类型、条件类型、模板字面量类型）
• 特定框架的模式（带泛型的 React hooks、Vue composables）
• 包含多个重载的复杂回调签名

对于这些情形，应优先使用清晰的自然语言描述，而不是不完整的 JSDoc 标签。

4. 使用报告模板（适用于明确要求的审查）

当用户明确要求进行文档审查或直接调用此技能（/accelint-ts-documentation <path>）时，请使用标准报告格式：

模板： assets/output-report-template.md

审查报告格式包括：

• 带有清晰前后示例的编号问题
• 分类（缺失、不完整、语法错误、质量、内部）
• 指向详细指南的参考资料（jsdoc.md、comments.md）
• 用于跟踪所有问题的汇总表

何时使用审查模板：

• 通过 /accelint-ts-documentation <path> 直接调用技能
• 用户明确要求“审查文档”或“审计文档”
• 用户要求“审查”某个或多个文件中的“所有文档”

何时不使用审查模板：

• 用户要求“为此函数添加 JSDoc”（直接实施）
• 用户询问“这条注释有什么问题？”（直接回答问题）
• 用户要求进行特定修改（直接应用修改，不提供正式报告）

文档审查中的反模式

执行文档审查时，请避免这些常见错误：

❌ 不正确：过度记录内部代码

// Internal utility with verbose documentation
/**
 * Internal helper function that validates input
 * @internal
 * @param x - The input value
 * @returns True if valid, false otherwise
 * @example
 * ```typescript
 * if (isValid(data)) { ... }
 * ```
 */
function isValid(x: unknown): boolean {
  return x != null;
}

为什么这是错误的：内部文档比公共 API 文档更容易过时，因为它们紧邻频繁变更的实现。团队成员直接阅读实际实现，比阅读会造成困惑的过时文档更快。应将全面的文档留给稳定的导出 API，因为使用者无法访问其实现。

✅ 正确：内部文档从简，公共 API 文档全面

// Internal utility - minimal documentation
/** Checks if value is not null/undefined */
function isValid(x: unknown): boolean {
  return x != null;
}

// Public API - comprehensive documentation even if "obvious"
/**
 * Validates user input data
 * @param data - User input to validate
 * @returns True if data is defined and not null
 * @example
 * ```typescript
 * if (validateInput(userData)) {
 *   processData(userData);
 * }
 * ```
 */
export function validateInput(data: unknown): boolean {
  return data != null;
}

❌ 不正确：记录如何实现，而非是什么／为什么

// JSDoc describes implementation details
/**
 * Loops through array using reduce to accumulate values into a sum
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

为什么这是错误的：API 使用者无法访问实现，但 JSDoc 会显示在 IDE 的自动补全中。在 JSDoc 中解释如何实现，会造成困惑（“为什么我会在自动补全中看到实现细节？”），还会扩大重构范围——每次实现变更都需要更新文档，导致文档与代码脱节。

✅ 正确：描述目的和行为，而非实现方式

/**
 * Calculates the sum of all numbers in the array
 * @param numbers - Array of numbers to sum
 * @returns The total sum, or 0 for empty array
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

❌ 不正确：使用含糊的注释标记

// Not actionable
// TODO: fix this
// TODO: improve performance

为什么这是错误的：“TODO: fix this”（待办：修复此问题）会导致责任分散。几个月后，没人知道这项待办是否仍然有效、应该由谁处理，或“此问题”指的是什么。含糊的标记会不断累积，形成噪声，降低大家对所有标记的信任，甚至让开发者忽略关键标记。

✅ 正确：使用明确且包含负责人和背景信息的标记

// TODO(username): Replace with binary search for O(log n) lookup
// FIXME(username): Throws error on empty array, add guard clause

文档质量示例

优秀的公共 API 文档

/**
 * Fetches user profile data from the authentication service
 *
 * Automatically retries up to 3 times on network failures with exponential
 * backoff. Throws if user is not authenticated or profile doesn't exist.
 *
 * @param userId - Unique identifier for the user profile to fetch
 * @param options - Configuration for fetch behavior
 * @param options.includeMetadata - Include account metadata (creation date, last login)
 * @param options.timeout - Request timeout in milliseconds (default: 5000)
 * @returns User profile with email, name, and optional metadata
 * @throws {AuthenticationError} When user session is expired or invalid
 * @throws {NotFoundError} When user profile doesn't exist
 * @throws {NetworkError} When all retry attempts are exhausted
 *
 * @example
 * ```typescript
 * // Basic usage
 * const profile = await fetchUserProfile('user-123');
 * console.log(profile.email);
 *
 * // With metadata and custom timeout
 * const profile = await fetchUserProfile('user-123', {
 *   includeMetadata: true,
 *   timeout: 10000
 * });
 * ```
 */
export async function fetchUserProfile(
  userId: string,
  options?: { includeMetadata?: boolean; timeout?: number }
): Promise<UserProfile> {
  // implementation
}

优秀之处：

• 描述隐藏行为（带指数退避的重试逻辑）
• 使用点号表示法记录对象参数（options.*）
• @throws 列出所有可能的错误及其触发条件
• @example 展示基础和进阶用法
• 提及默认值和限制（超时默认值：5000）
• 关注是什么／为什么（用户需求），而非如何实现（实现细节）

冲突解决原则

当判断相互冲突时，按以下优先级处理：

1. 一致性 > 完美：遵循现有代码库的模式
2. 使用者 > 维护者：公共 API 文档面向不了解你所掌握背景的用户，应尽可能全面
3. 意图 > 实现：记录是什么／为什么，而非如何实现
4. 稳定 > 频繁变更：稳定代码应编写全面文档，频繁变更的代码则应从简
5. 未来清晰度测试：“这能在 6 个月后帮到我吗？”如果不能，就删掉

边缘情况需要加载参考资料

复杂场景（已弃用的 API、重载函数、泛型工具类型、回调参数、构建器模式、事件发射器）需要详细的语法指导。遇到这些情况时：

加载 jsdoc.md 参考资料 ——其中包含所有边缘情况的全面示例以及正确的语法模式。

核心原则：边缘情况仍遵循双层规则（导出代码与内部代码），但语法细节更为重要。不要猜测——加载参考资料。