svg-sprites/preview/ai/basics/documentation.md

---
title: Документирование
scope: basics
keywords: [JSDoc, комментарий, документирование, описание функции, описание компонента]
when: "Документирование кода: JSDoc для функций, компонентов, типов"
---
# Документирование

Этот раздел описывает правила документирования кода: когда и как писать
комментарии к компонентам, функциям, типам и интерфейсам.

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

- Документировать публичные функции, компоненты, типы, интерфейсы и enum.
- Не документировать очевидное — если название говорит само за себя, комментарий не нужен.
- Не документировать параметры, возвращаемые значения и типы пропсов — они видны из сигнатуры.
- Описание через пользу и назначение, а не через внутреннюю реализацию.
- Описание завершается точкой.

## Функции

Для документирования функций используется шаблон. Описание механики опционально —
добавляется когда логика нетривиальна.

**Шаблон**
```ts
/**
 * <Что делает функция в 1 строке>.
 *
 * <Опционально: описание сложной механики или важных нюансов>.
 */
```

**Хорошо**
```ts
/**
 * Форматирует цену с символом валюты.
 */
export const formatPrice = (value: number): string => { ... }

/**
 * Рекурсивно собирает дерево категорий из плоского списка.
 *
 * Группирует элементы по parentId, начиная с корневых (parentId = null).
 * Категории без родителя попадают в корень дерева.
 */
export const buildCategoryTree = (categories: Category[]): CategoryTree[] => { ... }
```

**Плохо**
```ts
// Плохо: дублирует сигнатуру.
/**
 * @param value - число
 * @returns строка с ценой
 */
```

## Компоненты

Компонент описывает своё **назначение** и **сценарии применения** — это помогает понять, когда и где его использовать, без необходимости читать реализацию.

**Шаблон**
```ts
/**
 * <Назначение компонента в 1 строке>.
 *
 * Используется для:
 *  - <сценарий 1>
 *  - <сценарий 2>
 *  - <сценарий 3>
 */
```

**Хорошо**
```tsx
/**
 * Контейнер с адаптивной максимальной шириной.
 *
 * Используется для:
 *  - обёртки контента страниц с ограничением ширины
 *  - центрирования блоков в лейауте
 */
export const Container = (props: ContainerProps) => { ... }
```

**Плохо**
```tsx
// Плохо: описывает реализацию, а не назначение.
/**
 * Рендерит div с className и htmlAttr.
 */

// Плохо: нет описания вообще.
export const Container = (props: ContainerProps) => { ... }
```

## Типы, интерфейсы, enum

Документируются назначение сущности и каждое её поле.

**Хорошо**
```ts
/**
 * Фильтры списка задач.
 */
export enum TodoFilter {
  /** Все задачи. */
  ALL = 'all',
  /** Только активные. */
  ACTIVE = 'active',
  /** Только завершённые. */
  COMPLETED = 'completed',
}

/**
 * Задача пользователя.
 */
export interface TodoItem {
  /** Уникальный идентификатор задачи. */
  id: string;
  /** Текст задачи. */
  text: string;
  /** Статус выполнения. */
  completed: boolean;
}
```

**Плохо**
```ts
// Плохо: описывает очевидное.
export interface TodoItem {
  /** id — это id */
  id: string;
}
```