S.Gromov
e77e7dfcf1
- Удалён shiki (9.5→0 МБ), создан regex-токенизатор для html/css/xml - CLI переведён с аргументов на конфиг-файл svg-sprites.config.ts - Превью переработано: React-приложение вместо инлайн HTML - Добавлен футер с названием пакета и ссылкой на репозиторий - Исправлена загрузка dev-data.js для Vite 8 - Футер прижат к низу, содержимое центрировано
137 lines
4.4 KiB
Markdown
137 lines
4.4 KiB
Markdown
---
|
||
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;
|
||
}
|
||
```
|