jsdoc

JSDoc

Общие правила

• Язык комментариев: русский (как в code-style и project-context).
• Документировать все экспортируемые сущности: функции, классы, методы, интерфейсы, типы, константы.
• Для внутренних (не экспортируемых) функций и типов — краткий JSDoc при неочевидном назначении.
• Файл: в начале модуля — один блок JSDoc с описанием назначения модуля (если не однострочный комментарий).

Формат

• Функция/метод: описание в одну строку или короткий абзац; при наличии параметров или возвращаемого значения — теги @param и @returns.
• Класс: назначение класса и откуда берутся параметры (например env, конфиг).
• Интерфейс/тип: одно предложение о назначении и ключевых полях.
• Константа/объект: что представляет (например «Уровни логирования», «Схема параметров инструментов»).

Теги

• @param {Type} name — описание — для параметров (тип опционален при наличии TypeScript).
• @returns описание — для возвращаемого значения (при неочевидном или важном).
• Не использовать @description отдельно — описание пишется в теле блока.

Примеры

/**
 * Преобразует commandId расширения в имя MCP-инструмента (укладывается в лимит длины).
 *
 * @param commandId — полный идентификатор команды
 * @returns имя инструмента для MCP
 */
export function commandIdToToolName(commandId: string): string { ... }

/** Настройки подключения к IPC-серверу (хост, порт, токен, таймаут). */
export interface IpcClientConfig { ... }

/**
 * Выполняет JSON-RPC запрос к IPC-серверу.
 *
 * @param method — имя метода (например listCommands, executeCommand)
 * @param params — опциональные параметры
 * @returns результат из response.result (при ошибке — reject с сообщением сервера)
 */
public async request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T> { ... }

Что не дублировать

• Не повторять в JSDoc то, что уже однозначно видно из сигнатуры и имени (например «возвращает Promise» для async-функции), если нет уточнений.
• Тесты: достаточно файлового JSDoc при необходимости; описание сценария оставлять в describe/it.