tsdoc-jsdoc-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TSDoc and JSDoc Authoring

TSDoc与JSDoc文档编写指南

Create high-quality documentation comments for functions, classes, interfaces, types, modules, and exported APIs.

为函数、类、接口、类型、模块及导出API创建高质量的文档注释。

When to Apply

适用场景

Use this skill when the user asks to:

add or improve code comments/docs
write TSDoc or JSDoc
document params, return values, thrown errors, or examples
standardize documentation style across files

当用户提出以下需求时，可使用本技能：

添加或优化代码注释/文档
编写TSDoc或JSDoc
记录参数、返回值、抛出错误或使用示例
统一多文件的文档风格

Routing (Read This First)

路由选择（请先阅读）

Choose one focused index before loading rule files:

TypeScript APIs and typed exports:
```
indexes/tsdoc-index.md
```
JavaScript authoring and shape docs:
```
indexes/jsdoc-authoring-index.md
```
Strict consistency/lint-safe output standards:
```
indexes/jsdoc-consistency-index.md
```

在加载规则文件前，请选择一个针对性的索引：

TypeScript API与类型化导出：
```
indexes/tsdoc-index.md
```
JavaScript文档编写与结构文档：
```
indexes/jsdoc-authoring-index.md
```
严格一致性/符合规范的输出标准：
```
indexes/jsdoc-consistency-index.md
```

Rule 1: Choose the Correct Standard

规则1：选择正确的标准

Use TSDoc for TypeScript code and typed public APIs.
Use JSDoc for JavaScript code or projects using JSDoc tooling.
Do not mix tag syntaxes from both standards in one comment block.

针对TypeScript代码和类型化公开API，使用TSDoc。
针对JavaScript代码或使用JSDoc工具的项目，使用JSDoc。
请勿在同一个注释块中混合使用两种标准的标签语法。

Workflow

工作流程

Read the target file and identify the symbol's purpose and side effects.
Prefer documenting exported/public APIs first.
Write a one-line summary in plain language.
Add only meaningful tags (no empty or redundant tags).
Validate tag names and formatting against the relevant standard.
Ensure comments match actual behavior (inputs, outputs, errors, async behavior).

读取目标文件，识别符号的用途和副作用。
优先为导出/公开API编写文档。
用简洁的语言编写一行摘要。
仅添加有意义的标签（避免空标签或冗余标签）。
根据相关标准验证标签名称和格式。
确保注释与实际行为一致（输入、输出、错误、异步行为等）。

Authoring Rules (Both Standards)

通用编写规则（两种标准均适用）

Describe intent and behavior, not obvious implementation details.
Keep summaries concise and action-oriented ("Returns...", "Creates...", "Parses...").
Document every parameter and explain what each parameter does.
If a parameter is an object, document each object property and what it does.
Use imperative, consistent phrasing for
```
@param
```
descriptions.
Document thrown errors with
```
@throws
```
when behavior depends on error handling.
Add
```
@example
```
only when it clarifies non-obvious usage.
Do not restate TypeScript types in prose unless it adds semantic meaning.

描述意图和行为，而非显而易见的实现细节。
摘要需简洁且以行为为导向（如“返回……”、“创建……”、“解析……”）。
记录每个参数并说明其作用。
若参数为对象，需记录每个对象属性及其作用。
```
@param
```
描述使用命令式、一致的措辞。
当行为依赖错误处理时，使用
```
@throws
```
记录抛出的错误。
仅当示例能阐明非显而易见的用法时，添加
```
@example
```
。
除非能补充语义信息，否则不要在描述中重复TypeScript类型。

TSDoc Rules

TSDoc规则

Use these tags by default when relevant:

```
@param
```
for each function argument
```
@typeParam
```
for generic parameters
```
@returns
```
for return semantics
```
@remarks
```
for longer contextual details
```
@throws
```
for exceptional behavior
```
@example
```
for practical usage
```
@deprecated
```
for migration guidance

TSDoc formatting reminders:

Use
```
@param name - Description
```
with a hyphen separator.
Prefer inline links with
```
{@link SymbolName}
```
.
Keep release tags (
```
@alpha
```
,
```
@beta
```
,
```
@public
```
,
```
@internal
```
) aligned with project policy.
For object parameters in TypeScript, prefer a named
```
type
```
or
```
interface
```
and add
```
/** ... */
```
comments on each property so VS Code hovers/autocomplete show per-property docs.

默认使用以下相关标签：

```
@param
```
：用于每个函数参数
```
@typeParam
```
：用于泛型参数
```
@returns
```
：用于返回语义
```
@remarks
```
：用于较长的上下文细节
```
@throws
```
：用于异常行为
```
@example
```
：用于实际用法
```
@deprecated
```
：用于迁移指导

TSDoc格式提醒：

使用
```
@param name - Description
```
格式，用连字符分隔。
优先使用
```
{@link SymbolName}
```
形式的内联链接。
确保发布标签（
```
@alpha
```
、
```
@beta
```
、
```
@public
```
、
```
@internal
```
）与项目政策保持一致。
对于TypeScript中的对象参数，优先使用命名
```
type
```
或
```
interface
```
，并为每个属性添加
```
/** ... */
```
注释，以便VS Code的悬浮提示/自动补全能显示每个属性的文档。

JSDoc Rules

JSDoc规则

Use these tags by default when relevant:

```
@param {Type} name
```
(with optional/default forms when needed)
```
@returns {Type}
```
(or
```
@return
```
)
```
@throws {Type}
```
when known
```
@typedef
```
and
```
@property
```
for reusable object shapes
```
@example
```
for usage snippets
```
@async
```
and
```
@yields
```
for async/generator behavior when needed

JSDoc formatting reminders:

Optional params:
```
@param {string} [name]
```
Optional with default:
```
@param {string} [name=John Doe]
```

Nested object props:

@param {Object} options

and

@param {string} options.mode

默认使用以下相关标签：

```
@param {Type} name
```
（必要时可使用可选/默认值形式）
```
@returns {Type}
```
（或
```
@return
```
）
```
@throws {Type}
```
：已知异常类型时使用
```
@typedef
```
和
```
@property
```
：用于可复用的对象结构
```
@example
```
：用于代码片段示例
```
@async
```
和
```
@yields
```
：必要时用于异步/生成器行为

JSDoc格式提醒：

可选参数：
```
@param {string} [name]
```
带默认值的可选参数：
```
@param {string} [name=John Doe]
```

嵌套对象属性：

@param {Object} options

搭配

@param {string} options.mode

JSDoc Consistency Standard

JSDoc一致性标准

Apply these rules by default in all JavaScript documentation, regardless of lint setup.

Keep
```
@access
```
usage consistent per block (
```
@access <level>
```
or one shorthand access tag).
Use
```
@implements
```
only on classes/constructors.
Prefer rule-specific guidance from the
```
rules/jsdoc/**
```
files when there is a conflict.

无论代码检查配置如何，所有JavaScript文档默认遵循以下规则：

每个块中
```
@access
```
的使用保持一致（使用
```
@access <level>
```
或一个简写的访问标签）。
仅在类/构造函数上使用
```
@implements
```
。
当存在冲突时，优先使用
```
rules/jsdoc/**
```
文件中的规则特定指导。

Output Expectations

输出预期

When updating comments:

keep existing project conventions unless user requests a migration
preserve behavior accuracy over verbosity
avoid adding comments to private/internal symbols unless requested

更新注释时：

除非用户要求迁移，否则保留现有项目的约定
优先保证行为准确性而非冗长性
除非用户要求，否则不要为私有/内部符号添加注释

Additional Reference

额外参考

For templates and tag cheat sheets, see reference.md.

如需模板和标签速查表，请查看reference.md。

Rule Files

规则文件

Use focused indexes to avoid loading unrelated rules:

TSDoc index:
```
indexes/tsdoc-index.md
```
JSDoc authoring index:
```
indexes/jsdoc-authoring-index.md
```
JSDoc consistency index:
```
indexes/jsdoc-consistency-index.md
```

使用针对性的索引来避免加载无关规则：

TSDoc索引：
```
indexes/tsdoc-index.md
```
JSDoc文档编写索引：
```
indexes/jsdoc-authoring-index.md
```
JSDoc一致性索引：
```
indexes/jsdoc-consistency-index.md
```

Full Compiled Document

完整编译文档

For the full rule index and category guide:

AGENTS.md

如需完整的规则索引和分类指南，请查看：

AGENTS.md