Правила JSDoc-документации (Frontend)

Цель: код фронтенда (src/front-ends/**) должен быть самодокументируемым. Все публичные типы, поля, компоненты и их props снабжаются JSDoc-комментариями. Это улучшает подсказки IDE, делает контракты компонентов явными и держит код и намерение в синхроне (правило «код = доки»).

Стиль согласован с тем, что ValIO генерирует в shared/api/generated/** (теги @description, @param, @returns, @type, @remarks). Сгенерированные файлы руками не трогаем — там JSDoc уже есть.

Что документируем обязательно

• Экспортируемые компоненты — блочный JSDoc над компонентом: что он рендерит/делает, ключевое поведение, особенности (a11y, состояния). При неочевидном использовании — @example.
• Props-интерфейсы и их поля — JSDoc над интерфейсом + комментарий /** … */ на каждом поле. Для значений по умолчанию — @default, для устаревших — @deprecated <чем заменить>.
• Экспортируемые хуки и функции — @param на каждый аргумент, @returns на результат, @throws если бросает, @template для дженериков.
• Типы/алиасы/value-object'ы и enum-обёртки — назначение и (для конечных множеств) смысл значений.
• Публичные утилиты shared/lib, shared/api/lib — сигнатура + поведение.

Что НЕ документируем

• Тривиальные/самоочевидные внутренние переменные и приватные хелперы внутри функции.
• Локальные типы, не выходящие за пределы файла, если их имя уже всё объясняет.
• Сгенерированные файлы (shared/api/generated/**) — только регенерация.
• Не дублируем тип в тексте («disabled: boolean — булево») — объясняем смысл, не повторяем сигнатуру.

Теги (используем)

Тег	Где	Назначение
@param	функции/хуки	описание аргумента
@returns	функции/хуки	описание результата
@template	дженерики	смысл параметра-типа (напр. @template T тип значения enum)
@default	поля props	значение по умолчанию
@example	компоненты/хуки	пример использования
@deprecated	поля/компоненты	помечает устаревшее + чем заменить
@see	любое	ссылка на связанный компонент/доку ({@link Foo})
@remarks	любое	важные оговорки/краевые случаи
@throws	функции	условие исключения

Поля интерфейса документируем построчными /** … */, а не @param (последний — для функций).

Язык и оформление

• JSDoc — на русском, UTF-8. Кратко и по делу; первая строка — суть.
• Один пустой между секциями тегов не нужен; держим компактно.
• Не описываем то, что видно из имени и типа; описываем намерение, инварианты, побочные эффекты.

Эталоны

Компонент + props (построчные доки полей, @template, @example):

interface SchemaFieldTypeNameInputProps<T extends string> {
  /** Список доступных типов поля (id + русская подпись). */
  typeOptions: readonly EnumOption<T>[];
  /** Текущий выбранный тип поля. */
  type: T;
  /** Текущее отображаемое имя поля. */
  displayName: string;
  /** Вызывается при смене типа поля. */
  onTypeChange: (type: T) => void;
  /** Вызывается при изменении названия поля. */
  onNameChange: (name: string) => void;
  /** Текст ошибки валидации под контролом; null/undefined — без ошибки. */
  error?: string;
}

/**
 * Объединённый ввод поля схемы: тип (выпадающий список) + название (текст) в одном блоке.
 * Машинный ключ поля отдельно не вводится — формируется на бэке из названия.
 * @template T строковый enum типа поля (`FieldType`, `DictionarySchemaFieldType`, …)
 * @see {@link FieldTypeNameInput} — обёртка для каталогьной схемы
 * @example
 * <SchemaFieldTypeNameInput typeOptions={FIELD_TYPE_OPTIONS} type={t} displayName={n}
 *   onTypeChange={setT} onNameChange={setN} />
 */
export function SchemaFieldTypeNameInput<T extends string>(props: SchemaFieldTypeNameInputProps<T>) { … }

Хук/функция (@param/@returns/@template):

/**
 * Возвращает поля схемы в исходном (серверном) порядке. Сортировка не нужна — порядок задаётся
 * позицией в массиве.
 * @template T тип элемента поля схемы
 * @param fields массив полей схемы (может быть null/undefined)
 * @returns копия массива полей в том же порядке
 */
export function sortedSchemaFields<T>(fields: T[] | null | undefined): T[] { … }

Применение

• Конвенция действует для нового кода и для файлов, которые редактируются (документируем по ходу правок — «boy-scout rule»). Массовый ретро-проход не обязателен, но shared-примитивы (shared/ui/**, shared/lib/**) документируем в первую очередь как опору для остального кода.
• Совместимо с frontend-rules.md, frontend-fsd-and-atomic-rules.md, frontend-form-field-behavior-rules.md, code-quality-standards.md.

Обратные ссылки

Автоссылки: где используется этот документ.

• frontend-rules.md (1): Правила Frontend Разработки