sync

OLD_parts/7-docs.md

@@ -0,0 +1,69 @@
+---
+title: Документирование
+---
+
+# Документирование
+
+## Правило для документирования кода
+
+- Документировать разрешено только описание (назначение) функций, компонентов, типов, интерфейсов, enum и их полей.
+- Строго запрещено документировать параметры, возвращаемые значения, типы пропсов, аргументы, возвращаемые значения функций, компоненты, хуки и т.д.
+- В интерфейсах, типах и enum разрешено документировать только смысл (описание) каждого поля или значения.
+- В React-компонентах, функциях, хранилищах, схемах, утилитах разрешено документировать только назначение (описание), без детализации параметров и возвращаемых значений.
+- Описание должно быть кратким, информативным и реально помогать понять структуру и бизнес-логику.
+- Не допускается избыточная или дублирующая очевидное документация.
+- В конце описания всегда ставить точку.
+
+**Примеры правильного документирования**
+```tsx
+/**
+ * Список задач пользователя.
+ */
+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 объект задачи
+ */
+
+// ❌ Не нужно:/
+/**
+ * @param props - пропсы компонента
+ * @returns JSX.Element
+ */
+
+// ❌ Не нужно:/
+/**
+ * id — идентификатор задачи
+ * text — текст задачи
+ * completed — статус выполнения
+ */
+```