# typescript-doc-comments

Правило typescript-doc-comments для написания документирующих комментариев в TypeScript по стандарту TSDoc. Помогает описать поведение и ограничения функций, типов и компонентов так, чтобы вызывающий код не ошибся.

- правило · `type=rule` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline · ★ 1627 у репозитория
- Автор: microsoft
- Лицензия: MIT · policy=mirror · начало файла — в конце страницы
- Исходник: https://github.com/microsoft/hve-core/tree/HEAD/.github/instructions/coding-standards/typescript/typescript-doc-comments.instructions.md
- Обновлён: 2026-10-25
- Проверка безопасности: автоматическая, 2026-11-16 (текст) — признаков вредоносного кода не нашли.
- HTML: https://affpapa.org/nevibecode/rules/typescript-doc-comments

## Что делает

Правило задаёт, когда и как документировать экспортируемые функции, классы, интерфейсы, компоненты, хуки и тестовые помощники. Основной принцип: добавлять в комментарий только то, что нельзя вывести из имени и сигнатуры типа. TypeScript уже выражает типы параметров, возвращаемые значения и модификаторы — комментарий расказывает про поведение, единицы измерения, побочные эффекты, порядок вызовов, граничные случаи и обработку ошибок.

Правило охватывает реусуемые API: публичные функции, классы, типы, интерфейсы, перечисления, UI-компоненты, хуки, помощники для тестов. Не требует переписывать старые комментарии — применяется при добавлении или изменении кода. Описывает синтаксис: `/** ... */` блок прямо над объявлением, краткая строка в начале, потом детали или `@remarks`, теги `@param`, `@returns`, `@throws`, `@typeParam`, `@example`, `@deprecated` только когда они добавляют информацию, не повторяют сигнатуру.

Правило работает с файлами `*.ts`, `*.tsx`, `*.mts`, `*.cts` и авторских деклараций (`.d.ts`, `.d.mts`, `.d.cts`). Не требует типизации в комментариях вроде `@param {string} name` — типы уже в коде.

## Установка

### GitHub Copilot (родная платформа)

**Вручную: положить файлы**
- Файл: `.github/instructions/typescript-doc-comments.instructions.md` — Поле applyTo задаёт, к каким файлам применять

### Claude Code

**Вручную: положить файлы**
- Файл: `.claude/rules/typescript-doc-comments.md` — Поле paths во frontmatter ограничивает файлы: applyTo из источника → paths

### Codex

**AGENTS.md**
- Codex читает AGENTS.md: вставьте текст правила туда

### Cursor

**Вручную: положить файлы**
- Файл: `.cursor/rules/typescript-doc-comments.mdc` — Во frontmatter: description, globs, alwaysApply. applyTo из источника → globs, иначе правило само не подключится

### Windsurf (Devin Desktop)

**Вручную: положить файлы**
- Файл: `.devin/rules/typescript-doc-comments.md`

### Cline

**Вручную: положить файлы**
- Файл: `.clinerules/typescript-doc-comments.md`

Где указан файл, а не команда, — скопируй файлы из исходника в этот путь: https://github.com/microsoft/hve-core/tree/HEAD/.github/instructions/coding-standards/typescript/typescript-doc-comments.instructions.md

## Когда брать
- Документировать функции и типы так, чтобы вызывающий не ошибся
- Выразить граничные случаи, единицы и побочные эффекты, которые не видны из сигнатуры
- Описать порядок вызовов, закрытие ресурсов и обработку ошибок для асинхронных API
- Избежать пустых или повторяющих сигнатуру комментариев
- Привести документацию в соответствие со стандартом TSDoc

## Примеры запросов агенту
- Добавлю на функцию комментарий с граничными условиями для `size` параметра и поведением на пустом входе
- Документирую React-хук с описанием побочных эффектов и того, когда колбэк срабатывает
- Напишу `@remarks` с уточнением, что функция не мутирует входные данные и сохраняет порядок

## Похожие
- [typescript-quality](https://affpapa.org/nevibecode/skills/typescript-quality.md) — скилл · 1100 установок
- [typescript](https://affpapa.org/nevibecode/skills/pymodel-typescript.md) — скилл · 657 установок
- [javascript-typescript-code-quality-cursorrules-pro](https://affpapa.org/nevibecode/rules/javascript-typescript-code-quality-cursorrules-pro.md) — правило · ★ 41178 у репозитория
- [jsdoc-typescript-docs](https://affpapa.org/nevibecode/skills/jsdoc-typescript-docs.md) — скилл · 572 установки
- [Doc Bridge](https://affpapa.org/nevibecode/mcp/doc-bridge.md) — MCP-сервер · ★ 10 у репозитория
- [doc-updater](https://affpapa.org/nevibecode/agents/affaan-mustafa-doc-updater.md) — субагент · ★ 6739 у репозитория

Из того же набора: [microsoft/hve-core](https://affpapa.org/nevibecode/by/microsoft/hve-core.md) — 148 карточек

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md
