65 lines
2.0 KiB
Markdown
65 lines
2.0 KiB
Markdown
---
|
||
title: Документирование
|
||
---
|
||
|
||
# Документирование
|
||
|
||
Документирование должно помогать понять назначение сущности, а не дублировать её типы или очевидные детали.
|
||
|
||
## Правила
|
||
|
||
- Документировать только назначение функций, компонентов, типов, интерфейсов и enum.
|
||
- Не документировать параметры, возвращаемые значения, типы пропсов и очевидные детали.
|
||
- В интерфейсах, типах и enum описывать только смысл поля или значения.
|
||
- Описание должно быть кратким, информативным и завершаться точкой.
|
||
|
||
## Примеры
|
||
|
||
**Хорошо**
|
||
```ts
|
||
/**
|
||
* Список задач пользователя.
|
||
*/
|
||
export const TodoList = memo(() => { ... });
|
||
|
||
/**
|
||
* Интерфейс задачи.
|
||
*/
|
||
export interface TodoItem {
|
||
/** Уникальный идентификатор задачи. */
|
||
id: string;
|
||
/** Текст задачи. */
|
||
text: string;
|
||
/** Статус выполнения задачи. */
|
||
completed: boolean;
|
||
}
|
||
|
||
/**
|
||
* Перечисление фильтров задач.
|
||
*/
|
||
export enum TodoFilter {
|
||
/** Все задачи. */
|
||
All = 'all',
|
||
/** Только активные задачи. */
|
||
Active = 'active',
|
||
/** Только выполненные задачи. */
|
||
Completed = 'completed',
|
||
}
|
||
```
|
||
|
||
**Плохо**
|
||
```ts
|
||
// Плохо: дублирование параметров и возвращаемых значений.
|
||
/**
|
||
* @param id - идентификатор задачи
|
||
* @returns объект задачи
|
||
*/
|
||
|
||
// Плохо: описание очевидных деталей.
|
||
/**
|
||
* id — идентификатор задачи
|
||
* text — текст задачи
|
||
* completed — статус выполнения
|
||
*/
|
||
```
|