typescript-tsdoc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TSDoc Generator

TSDoc 生成器

Воркфлоу добавления TSDoc-комментариев в TypeScript / Vue-код. Применять при любой задаче «добавь доки / задокументируй».

为TypeScript/Vue代码添加TSDoc注释的工作流程。适用于任何要求「添加文档/编写文档」的任务。

Базовые правила

基本规则

Стандарт: строгий TSDoc (tsdoc.org). Теги вне спецификации не использовать:
```
@type
```
,
```
@function
```
,
```
@kind
```
,
```
@property
```
,
```
@class
```
,
```
@method
```
,
```
@constructor
```
,
```
@module
```
— запрещены.
Язык описаний: русский. Имена символов — латиница как есть.
Scope: документировать только символы без существующего блока. Уже задокументированные не трогать, пока пользователь явно не попросит переписать.
@example
: не добавлять автоматически. Только по явной просьбе пользователя.
Не дублировать типы: TS уже знает сигнатуру. Не писать «возвращает
```
number
```
» — описывать смысл, а не типы.
Без тавтологий: если описание повторяет имя символа (
```
getUser
```
→ «получает пользователя») и не добавляет информации — не писать summary вообще и переходить к тегам.
Private remarks: внутренние заметки для разработчиков — через
```
@privateRemarks
```
, не в
```
@remarks
```
.

标准：严格遵循TSDoc规范（tsdoc.org）。禁止使用规范外的标签：
```
@type
```
、
```
@function
```
、
```
@kind
```
、
```
@property
```
、
```
@class
```
、
```
@method
```
、
```
@constructor
```
、
```
@module
```
— 均被禁用。
描述语言：俄语。符号名称保留原拉丁拼写。
范围：仅为无现有文档块的符号添加文档。已添加文档的符号请勿修改，除非用户明确要求重写。
@example
：请勿自动添加。仅在用户明确要求时添加。
不重复类型：TypeScript已知晓签名信息。请勿写「返回
```
number
```
」——应描述含义而非类型。
避免同义反复：如果描述重复符号名称（如
```
getUser
```
→「获取用户」）且未补充额外信息——请勿编写摘要，直接添加标签即可。
私有备注：面向开发者的内部备注请使用
```
@privateRemarks
```
，而非
```
@remarks
```
。

Формат блока

文档块格式

/**
 * Краткая суть в одном предложении с точкой.
 *
 * @remarks
 * Нетривиальные детали: инварианты, side-effects, ограничения.
 *
 * @typeParam T — Назначение параметра типа.
 *
 * @param name — Что передаётся и зачем.
 *
 * @returns Что возвращается (без указания типа).
 *
 * @throws {ErrorType} Когда бросается.
 *
 * @defaultValue Значение по умолчанию для опционального поля.
 *
 * @deprecated Причина + чем заменить.
 *
 * @see {@link OtherSymbol}
 */

Правила оформления:

Открывающий
```
/**
```
, закрывающий
```
 */
```
, каждая промежуточная строка начинается с
```
*
```
.
Первая строка — summary: одно предложение, заканчивается точкой.
Между summary и блочными тегами — пустая строка
```
 *
```
.
Между каждым блочным тегом (
@param
,
@returns
,
@throws
,
@typeParam
,
@defaultValue
,
@deprecated
,
@see
) — пустая строка
*
. Теги не ставятся подряд без разделения.

Порядок тегов:

@remarks

→

@typeParam

→

@param

→

@returns

→

@throws

→

@defaultValue

→

@deprecated

→

@see

→

@example

Разделитель между именем параметра и описанием —
```
—
```
(длинное тире с пробелами вокруг).
Описания внутри тегов начинаются с заглавной буквы (в том числе после
```
—
```
в
```
@param
```
и
```
@typeParam
```
) и заканчиваются точкой.

/**
 * 一句话简要说明，以句号结尾。
 *
 * @remarks
 * 非平凡细节：不变量、副作用、限制条件。
 *
 * @typeParam T — 类型参数的用途。
 *
 * @param name — 参数的传递内容及用途。
 *
 * @returns 返回值的含义（无需指定类型）。
 *
 * @throws {ErrorType} 抛出异常的场景。
 *
 * @defaultValue 可选字段的默认值。
 *
 * @deprecated 废弃原因及替代方案。
 *
 * @see {@link OtherSymbol}
 */

格式规则：

起始标记
```
/**
```
，结束标记
```
 */
```
，中间每一行均以
```
*
```
开头。
第一行是摘要：一句完整句子，以句号结尾。
摘要与块级标签之间需添加空行
```
 *
```
。
每个块级标签（
@param
、
@returns
、
@throws
、
@typeParam
、
@defaultValue
、
@deprecated
、
@see
）之间需添加空行
*
。标签不可连续排列，必须分隔。

标签顺序：

@remarks

→

@typeParam

→

@param

→

@returns

→

@throws

→

@defaultValue

→

@deprecated

→

@see

→

@example

。

参数名称与描述之间的分隔符为
```
—
```
（两侧带空格的长破折号）。
标签内的描述需以大写字母开头（包括
```
@param
```
和
```
@typeParam
```
中
```
—
```
之后的内容），并以句号结尾。

Workflow

工作流程

Определить цель — какие файлы/символы просил документировать пользователь. Если не указано явно — уточнить.
Отфильтровать — пропустить все символы, у которых уже есть
```
/** */
```
блок.
Для каждого нового блока:
- Прочитать реализацию, понять назначение и контракт.
- Написать summary по сути (если не получается не-тавтологичное — пропустить summary, оставить только теги).
- Добавить
```
@param
```
  для каждого параметра,
```
@returns
```
  для функций с non-void возвратом,
```
@typeParam
```
  для дженериков.
- ```
@throws
```
  — только если функция действительно кидает (не ловит сама) или вызывает что-то кидающее наружу.
- ```
@remarks
```
  — только при наличии нетривиальных деталей (side-effects, порядок инициализации, race condition-ы, ограничения).
- ```
@deprecated
```
  — при пометке устаревшим, всегда с указанием чем заменить.
@example
не добавлять, если пользователь не попросил.
Проверить self-check в конце.

明确目标——确定用户要求为哪些文件/符号添加文档。若未明确指定，需向用户确认。
过滤筛选——跳过所有已存在
```
/** */
```
文档块的符号。
为每个新文档块执行以下操作：
- 阅读实现代码，理解符号用途与契约。
- 编写符合符号本质的摘要（若无法写出非同义反复的内容——跳过摘要，仅保留标签）。
- 为每个参数添加
```
@param
```
  ，为非void返回值的函数添加
```
@returns
```
  ，为泛型添加
```
@typeParam
```
  。
- ```
@throws
```
  ——仅当函数确实会抛出异常（自身捕获的不算）或调用了会向外抛出异常的代码时添加。
- ```
@remarks
```
  ——仅当存在非平凡细节（副作用、初始化顺序、竞态条件、限制条件）时添加。
- ```
@deprecated
```
  ——仅当符号被标记为废弃时添加，且需说明废弃原因及替代方案。
若用户未要求，请勿添加
@example
。
完成后执行自我检查。

Детальные справочники

详细参考文档

references/tags.md — полный перечень разрешённых TSDoc-тегов и когда применять.
references/examples.md — before/after по типам символов (function, class, interface, type alias, enum, generic).
references/vue-patterns.md — Vue-специфика: composables,
```
defineProps
```
,
```
defineEmits
```
,
```
defineModel
```
,
```
defineSlots
```
.

references/tags.md——允许使用的TSDoc标签完整列表及使用场景说明。
references/examples.md——各类符号（函数、类、接口、类型别名、枚举、泛型）的文档添加前后示例对比。
references/vue-patterns.md——Vue专属规范：composables、
```
defineProps
```
、
```
defineEmits
```
、
```
defineModel
```
、
```
defineSlots
```
。

Self-check

自我检查清单

Все описания на русском.
Использованы только теги из TSDoc-спецификации.
Нет дублирования типов из сигнатуры в тексте описаний.
Нет тавтологий, повторяющих имя символа.
Порядок тегов соответствует разделу «Формат блока».
Существующие блоки не изменены (только новые добавлены).
```
@example
```
отсутствует, если его не просили.
Для Vue-специфики (composables,
```
defineProps
```
/
```
defineEmits
```
) применены паттерны из
```
references/vue-patterns.md
```
.

所有描述均为俄语。
仅使用TSDoc规范内的标签。
描述中未重复签名中的类型信息。
无重复符号名称的同义反复内容。
标签顺序符合「文档块格式」章节要求。
未修改现有文档块（仅添加新文档块）。
若用户未要求，未添加
```
@example
```
。
Vue专属内容（composables、
```
defineProps
```
/
```
defineEmits
```
）遵循
```
references/vue-patterns.md
```
中的规范。