accelint-ts-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Documentation Skill

代码文档技能

Comprehensive skill for improving JavaScript/TypeScript documentation, including JSDoc comments, comment markers, and general comment quality.

全面提升JavaScript/TypeScript文档质量的技能，涵盖JSDoc注释、注释标记及通用注释质量优化。

When to Activate This Skill

何时激活本技能

Use this skill when the task involves:

当任务涉及以下内容时，使用本技能：

JSDoc Documentation

JSDoc文档编写

Adding JSDoc comments to exported functions, types, interfaces, or classes
Validating JSDoc completeness (missing @param, @returns, @template tags)
Ensuring JSDoc @example tags use proper code fences
Documenting object parameters with destructuring using dot notation

为导出的函数、类型、接口或类添加JSDoc注释
验证JSDoc的完整性（检查是否缺失@param、@returns、@template标签）
确保JSDoc的@example标签使用正确的代码围栏格式
使用点符号为解构后的对象参数编写文档

Comment Quality

注释质量优化

Identifying and categorizing comments using proper markers (TODO, FIXME, HACK, NOTE, PERF, REVIEW, DEBUG, REMARK)
Removing unnecessary comments (commented-out code, edit history, obvious statements)
Preserving important comments (markers, linter directives, business logic)
Improving comment placement (moving end-of-line comments above code)

使用标准标记（TODO、FIXME、HACK、NOTE、PERF、REVIEW、DEBUG、REMARK）识别并分类注释
移除不必要的注释（被注释的代码、编辑历史、显而易见的语句）
保留重要注释（标记、检查器指令、业务逻辑说明）
优化注释位置（将行尾注释移至代码上方）

Documentation Audits

文档审核

Reviewing code for documentation completeness
Ensuring exported code has comprehensive documentation
Validating internal code has minimum required documentation

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

When NOT to Use This Skill

何时不应使用本技能

Do not activate for:

General code quality issues (use accelint-ts-best-practices instead)
Performance optimization (use accelint-ts-performance instead)
Type safety improvements (use accelint-ts-best-practices instead)
Framework-specific documentation (React PropTypes, Vue props, etc.)

请勿在以下场景激活本技能：

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

How to Use

使用方法

1. Load References Based on Task Type

1. 根据任务类型加载参考文档

For JSDoc additions/validation:

MANDATORY: Read

jsdoc.md

in full before implementing. Critical content: @example code fence syntax (failures common here), object parameter dot notation, @template requirements, edge cases.

Do NOT load

comments.md

unless the task explicitly mentions comment markers (TODO, FIXME, etc.) or comment quality issues.

For comment quality audits:

MANDATORY: Read

comments.md

in full before implementing. Critical content: Comment marker standards, what to remove vs preserve, placement rules.

Do NOT load

jsdoc.md

unless the task explicitly mentions JSDoc tags (@param, @returns, etc.) or function/type documentation.

Do NOT load any references when only answering questions (not implementing changes) or task is general code quality.

针对JSDoc添加/验证任务：

强制要求：在执行任务前完整阅读

jsdoc.md

。关键内容：@example代码围栏语法（此处错误率较高）、对象参数点符号、@template要求、边缘场景处理。

请勿加载

comments.md

，除非任务明确提及注释标记（TODO、FIXME等）或注释质量问题。

针对注释质量审核任务：

强制要求：在执行任务前完整阅读

comments.md

。关键内容：注释标记标准、需移除与需保留的注释类型、注释位置规则。

请勿加载

jsdoc.md

，除非任务明确提及JSDoc标签（@param、@returns等）或函数/类型文档。

仅回答问题（不执行修改）或任务为通用代码质量优化时，请勿加载任何参考文档。

2. Expert Judgment Framework

2. 专家判断框架

Apply this thinking framework before auditing:

Question 1: Who is the reader?

API consumers: Lack implementation context → Document comprehensively
Team members: Have codebase context → Document non-self-evident behaviors only
Future you (6 months): Will forget subtle decisions → Document rationale

Question 2: Opacity vs Complexity?

Opacity = Intent is hidden → Must document (e.g., cache.invalidate() - why? performance? correctness?)
Complexity = Implementation is intricate → Implementation comments, not JSDoc

Question 3: Maintenance cost trade-off?

High churn code: Minimal docs (won't stay accurate)
Stable API: Comprehensive docs (will stay accurate)
Internal utilities: Brief docs (low reader count × low frequency = minimal ROI)

在执行审核前，应用以下思考框架：

问题1：阅读对象是谁？

API使用者：缺乏实现上下文 → 需编写全面文档
团队成员：熟悉代码库上下文 → 仅需记录非自明的行为
未来的自己（6个月后）：会遗忘细节决策 → 需记录设计理由

问题2：是不透明性还是复杂性？

不透明性 = 意图隐藏 → 必须编写文档（例如：cache.invalidate() - 为什么这么做？为了性能？还是正确性？）
复杂性 = 实现逻辑复杂 → 编写实现注释，而非JSDoc

问题3：维护成本权衡？

高迭代代码：极简文档（无法保证准确性）
稳定API：全面文档（可长期保持准确）
内部工具：简短文档（读者数量少×使用频率低 = 投资回报率极低）

Two-Tier Decision Rule

双层决策规则

After applying the thinking framework:

Is this exported (public API)? → YES: Comprehensive documentation REQUIRED

All @param, @returns, @template, @throws, @example
Even if "obvious" - consumers lack your context

Is this internal code? → Apply judgment: Document what's NOT self-evident from:

Function name and type signature
Parameter names and types
Standard patterns in the codebase

Rule of thumb: If a competent team member would ask "why?" or "what's the edge case?" - document it. If they'd say "obvious" - skip it.

应用思考框架后：

该代码是否为导出的（公开API）？ → 是：层级1：需编写全面文档

包含所有@param、@returns、@template、@throws、@example标签
即使内容“显而易见”也需编写，因为使用者缺乏你的上下文

该代码是否为内部代码？ → 按需判断：仅记录以下非自明内容：

函数名称和类型签名无法体现的信息
参数名称和类型无法体现的信息
代码库中的非标准模式

经验法则：如果资深团队成员会问“为什么？”或“边缘场景是什么？”，就编写文档；如果他们觉得“显而易见”，则无需编写。

3. Evaluating Documentation Sufficiency

3. 评估文档充分性

Use this decision tree to determine if documentation is complete:

Step 1: Determine visibility tier

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

Step 2: Apply entity-specific requirements

Tier 1 (Exported) - Always Required:

Description (purpose, usage context, "when to use" for appropriate entities)
All @param with property documentation for objects
@returns (unless void)
@template with constraint explanations for generics
@throws with triggering conditions
At least one realistic @example

Tier 2 (Internal) - Judgment-Based:

Brief description (one line acceptable)
@param for non-obvious parameters only
@returns if non-obvious
@template for generics
@example only if behavior is complex

Entity-Specific Additions:

Classes (Tier 1): Constructor docs, public method docs, instantiation example
Types/Interfaces (Tier 1): Property descriptions for all public properties
Constants/Variables: Units/constraints if applicable (e.g., "milliseconds", "must be positive")

Sufficiency Checklist:

Before marking documentation as "sufficient", verify:

All exported items have comprehensive documentation
All @param tags describe what the parameter does (not just type info)
All @returns tags describe what is returned in different scenarios
All @example tags use proper code fences with language identifier
No @returns on void functions
Generic functions have @template for each type parameter
Object parameters use dot notation for property documentation
Descriptions focus on WHAT/WHY, not HOW

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

步骤1：确定可见性层级

是否为导出的（公开API）？
  是 → 层级1：需编写全面文档
  否 → 层级2：基于判断的极简文档

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

层级1（导出代码）- 必须包含：

描述（用途、使用场景、适用实体的“何时使用”说明）
所有@param标签，含对象属性文档
@returns（除非返回值为void）
@template，含泛型约束说明
@throws，含触发条件
至少一个真实场景的@example

层级2（内部代码）- 按需包含：

简短描述（一行即可）
仅为非自明参数添加@param
仅为非自明返回值添加@returns
泛型函数需添加@template
仅当行为复杂时添加@example

实体特定补充要求：

类（层级1）：构造函数文档、公共方法文档、实例化示例
类型/接口（层级1）：所有公共属性的描述
常量/变量：适用的单位/约束（例如：“毫秒”、“必须为正数”）

充分性检查清单：

在标记文档为“充分”前，验证以下内容：

所有导出项均有全面文档
所有@param标签描述参数用途（而非仅类型信息）
所有@returns标签描述不同场景下的返回值
所有@example标签使用带语言标识的正确代码围栏
void函数未添加@returns
泛型函数为每个类型参数添加@template
对象参数使用点符号编写属性文档
描述聚焦于WHAT/WHY（用途/理由），而非HOW（实现细节）

4. When References Are Insufficient

4. 参考文档不足时的处理

If you encounter scenarios not covered in references or standard patterns:

Fallback strategy:

Apply the two-tier rule (export vs internal) as your foundation
Prioritize clarity over completeness - better to document what you know than guess syntax
Use standard JSDoc conventions from TypeScript/JSDoc official documentation

Document your uncertainty with a NOTE marker:

// NOTE: JSDoc syntax may need review for [specific case]

If truly ambiguous, ask the user for clarification rather than making assumptions

Common uncovered scenarios:

Exotic TypeScript features (mapped types, conditional types, template literal types)
Framework-specific patterns (React hooks with generics, Vue composables)
Complex callback signatures with multiple overloads

For these, default to clear descriptions in natural language rather than incomplete JSDoc tags.

若遇到参考文档或标准模式未覆盖的场景：

** fallback策略：**

以双层规则（导出vs内部）为基础
优先保证清晰性而非完整性 - 与其猜测语法，不如记录已知内容
遵循TypeScript/JSDoc官方文档中的标准约定

使用NOTE标记记录不确定性：

// NOTE: JSDoc语法可能需针对[特定场景]进行审核

若确实存在歧义，向用户寻求澄清，而非自行假设

常见未覆盖场景：

特殊TypeScript特性（映射类型、条件类型、模板字面量类型）
框架特定模式（带泛型的React Hooks、Vue组合式函数）
含多个重载的复杂回调签名

对于这些场景，优先使用自然语言编写清晰描述，而非不完整的JSDoc标签。

4. Use the Report Template (For Explicit Audit Requests)

4. 使用报告模板（针对明确的审核请求）

When users explicitly request a documentation audit or invoke the skill directly (

/accelint-ts-documentation <path>

), use the standardized report format:

Template:

assets/output-report-template.md

The audit report format provides:

Numbered findings with clear before/after examples
Categorization (Missing, Incomplete, Incorrect Syntax, Quality, Internal)
References to detailed guidance (jsdoc.md, comments.md)
Summary table for tracking all issues

When to use the audit template:

Skill invoked directly via
```
/accelint-ts-documentation <path>
```
User explicitly requests "documentation audit" or "audit documentation"
User asks to "review all documentation" across file(s)

When NOT to use the audit template:

User asks to "add JSDoc to this function" (direct implementation)
User asks "what's wrong with this comment?" (answer the question)
User requests specific fixes (apply fixes directly without formal report)

当用户明确要求进行文档审核或直接调用本技能（

/accelint-ts-documentation <path>

）时，使用标准化报告格式：

模板：

assets/output-report-template.md

审核报告格式包含：

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

何时使用审核模板：

通过
```
/accelint-ts-documentation <path>
```
直接调用本技能
用户明确请求“文档审核”或“audit documentation”
用户要求“审核所有文档”（跨文件）

何时不应使用审核模板：

用户要求“为该函数添加JSDoc”（直接执行修改）
用户询问“这个注释有什么问题？”（直接回答问题）
用户请求特定修复（直接应用修复，无需正式报告）

Documentation Audit Anti-Patterns

文档审核反模式

When performing documentation audits, avoid these common mistakes:

执行文档审核时，避免以下常见错误：

❌ Incorrect: Over-documenting internal code

❌ 错误做法：过度编写内部代码文档

typescript

// 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;
}

Why this is wrong: Internal docs rot faster than public API docs because they're adjacent to frequently-changed implementation. Team members can read the actual implementation faster than reading outdated documentation that creates confusion. Reserve comprehensive docs for stable exported APIs where consumers cannot access implementation.

typescript

// 内部工具，文档过于冗长
/**
 * 验证输入的内部辅助函数
 * @internal
 * @param x - 输入值
 * @returns 有效返回true，无效返回false
 * @example
 * ```typescript
 * if (isValid(data)) { ... }
 * ```
 */
function isValid(x: unknown): boolean {
  return x != null;
}

错误原因：内部文档比公开API文档更容易过时，因为它们紧邻频繁修改的实现。团队成员阅读实际实现的速度比阅读可能过时且造成混淆的文档更快。仅为稳定的导出API编写全面文档，因为使用者无法访问实现细节。

✅ Correct: Minimal internal docs, comprehensive public API docs

✅ 正确做法：内部代码极简文档，公开API全面文档

typescript

// 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;
}

typescript

// 内部工具 - 极简文档
/** 检查值是否不为null/undefined */
function isValid(x: unknown): boolean {
  return x != null;
}

// 公开API - 即使内容“显而易见”也需编写全面文档
/**
 * 验证用户输入数据
 * @param data - 待验证的用户输入
 * @returns 若数据已定义且不为null则返回true
 * @example
 * ```typescript
 * if (validateInput(userData)) {
 *   processData(userData);
 * }
 * ```
 */
export function validateInput(data: unknown): boolean {
  return data != null;
}

❌ Incorrect: Documenting HOW instead of WHAT/WHY

❌ 错误做法：记录HOW（实现细节）而非WHAT/WHY（用途/理由）

typescript

// 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);
}

Why this is wrong: JSDoc appears in IDE autocomplete for API consumers who don't have access to implementation. Explaining HOW in JSDoc creates confusion ("why am I seeing implementation details in my autocomplete?") and increases refactoring surface area - every implementation change requires doc updates, leading to drift.

typescript

// JSDoc描述实现细节
/**
 * 使用reduce遍历数组，将值累加为总和
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

错误原因：JSDoc会出现在IDE自动补全中，而API使用者无法访问实现细节。在JSDoc中解释HOW会造成混淆（“为什么我在自动补全中看到实现细节？”），同时增加重构工作量——每次实现变更都需更新文档，导致文档与实现脱节。

✅ Correct: Describe purpose and behavior, not implementation

✅ 正确做法：描述用途和行为，而非实现细节

typescript

/**
 * 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);
}

typescript

/**
 * 计算数组中所有数字的总和
 * @param numbers - 待求和的数字数组
 * @returns 总和，空数组返回0
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

❌ Incorrect: Using vague comment markers

❌ 错误做法：使用模糊的注释标记

typescript

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

Why this is wrong: "TODO: fix this" creates diffusion of responsibility. After months pass, nobody knows if it's still relevant, who should fix it, or what "this" refers to. Vague markers accumulate as noise that reduces trust in ALL markers, making developers ignore even critical ones.

typescript

// 不具备可执行性
// TODO: fix this
// TODO: improve performance

错误原因：“TODO: fix this”会导致责任分散。数月后，没人知道该问题是否仍需处理、谁负责修复，或者“this”具体指什么。模糊的标记会累积成噪音，降低开发者对所有标记的信任度，甚至忽略关键标记。

✅ Correct: Specific markers with ownership and context

✅ 正确做法：使用明确的标记，含责任人与上下文

typescript

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

typescript

// TODO(username): 替换为二分查找以实现O(log n)查找效率
// FIXME(username): 空数组会抛出错误，添加守卫语句

Documentation Quality Example

文档质量示例

Excellent Public API Documentation

优秀的公开API文档

typescript

/**
 * 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
}

What makes this excellent:

Describes hidden behaviors (retry logic with exponential backoff)
Documents object parameters with dot notation (options.*)
@throws lists all possible errors with triggering conditions
@example shows both basic and advanced usage patterns
Mentions defaults and constraints (timeout default: 5000)
Focuses on WHAT/WHY (user needs), not HOW (implementation details)

typescript

/**
 * 从认证服务获取用户资料数据
 *
 * 网络失败时自动重试最多3次，采用指数退避策略。用户未认证或资料不存在时抛出错误。
 *
 * @param userId - 待获取的用户资料唯一标识符
 * @param options - 请求行为配置
 * @param options.includeMetadata - 是否包含账户元数据（创建日期、最后登录时间）
 * @param options.timeout - 请求超时时间（毫秒，默认：5000）
 * @returns 包含邮箱、姓名及可选元数据的用户资料
 * @throws {AuthenticationError} 用户会话过期或无效时抛出
 * @throws {NotFoundError} 用户资料不存在时抛出
 * @throws {NetworkError} 所有重试尝试失败时抛出
 *
 * @example
 * ```typescript
 * // 基础用法
 * const profile = await fetchUserProfile('user-123');
 * console.log(profile.email);
 *
 * // 包含元数据与自定义超时
 * const profile = await fetchUserProfile('user-123', {
 *   includeMetadata: true,
 *   timeout: 10000
 * });
 * ```
 */
export async function fetchUserProfile(
  userId: string,
  options?: { includeMetadata?: boolean; timeout?: number }
): Promise<UserProfile> {
  // 实现代码
}

优秀原因：

描述了隐藏行为（指数退避重试逻辑）
使用点符号为对象参数编写文档（options.*）
@throws列出所有可能的错误及触发条件
@example展示基础与高级两种使用模式
提及默认值与约束（超时默认值：5000）
聚焦于WHAT/WHY（用户需求），而非HOW（实现细节）

Conflict Resolution Principles

冲突解决原则

When judgment calls conflict, apply these priorities:

Consistency > Perfection: Follow existing codebase patterns
Consumer > Maintainer: Public API docs serve users without your context - be comprehensive
Intent > Implementation: Document WHAT/WHY, not HOW
Stable > Churning: Comprehensive docs for stable code, minimal for high-churn code
Future clarity test: "Would this help me in 6 months?" If no, remove it

当判断结果存在冲突时，按以下优先级处理：

一致性 > 完美性：遵循代码库现有模式
使用者 > 维护者：公开API文档服务于无上下文的使用者，需全面
意图 > 实现：记录WHAT/WHY，而非HOW
稳定代码 > 高迭代代码：稳定代码需全面文档，高迭代代码仅需极简文档
未来清晰度测试：“这能帮到6个月后的我吗？”如果不能，移除它

Edge Cases Require Reference Loading

边缘场景需加载参考文档

Complex scenarios (deprecated APIs, overloaded functions, generic utility types, callback parameters, builder patterns, event emitters) require detailed syntax guidance. When encountering these:

Load jsdoc.md reference - Contains comprehensive examples for all edge cases with correct syntax patterns.

Key principle: Edge cases still follow the two-tier rule (export vs internal), but syntax details matter more. Don't guess - load the reference.

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

加载jsdoc.md参考文档 - 包含所有边缘场景的全面示例及正确语法模式。

核心原则：边缘场景仍需遵循双层规则（导出vs内部），但语法细节更为重要。不要猜测，直接加载参考文档。