Документирование

Документирование должно помогать понять назначение сущности, а не дублировать её типы или очевидные детали.

Правила

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

Примеры

Хорошо

/**
 * Список задач пользователя.
 */
export const TodoList = memo(() => { ... });

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

/**
 * Перечисление фильтров задач.
 */
export enum TodoFilter {
  /** Все задачи. */
  All = 'all',
  /** Только активные задачи. */
  Active = 'active',
  /** Только выполненные задачи. */
  Completed = 'completed',
}

Плохо

// Плохо: дублирование параметров и возвращаемых значений.
/**
 * @param id - идентификатор задачи
 * @returns объект задачи
 */

// Плохо: описание очевидных деталей.
/**
 * id — идентификатор задачи
 * text — текст задачи
 * completed — статус выполнения
 */