sync

parts/5-documentation.md

@@ -0,0 +1,64 @@
+---
+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 — статус выполнения
+ */
+```