Перейти к основному содержимому

JSDoc Standards & Guidelines

Стандарты документирования кода с помощью JSDoc для обеспечения консистентности и качества документации.

📋 Общие принципы​

1. Обязательная документация​

Все публичные компоненты, функции и хуки ДОЛЖНЫ иметь JSDoc документацию.

2. Язык документации​

  • Описания компонентов - на русском языке
  • Технические термины - на английском (props, state, etc.)
  • Примеры кода - комментарии на русском, код на английском

3. Структура комментариев​

/**
 * Краткое описание (одна строка)
 * 
 * Подробное описание функциональности.
 * Может занимать несколько строк.
 * 
 * Features:
 * - Список ключевых возможностей
 * - Важные особенности
 * - Ограничения или требования
 * 
 * @example
 * ```tsx
 * // Пример использования
 * <Component prop="value" />
 * ```
 * 
 * @param paramName - Описание параметра
 * @returns Описание возвращаемого значения
 * @since 1.0.0
 */

🧩 Стандарты для компонентов​

React компоненты​

/**
 * Название компонента - краткое описание назначения
 * 
 * Подробное описание функциональности компонента,
 * его роли в системе и основных возможностей.
 * 
 * Features:
 * - Список ключевых возможностей
 * - Поддерживаемые варианты и состояния
 * - Интеграции с другими компонентами
 * - Оптимизации производительности
 * - Доступность (accessibility)
 * 
 * @example
 * ```tsx
 * // Базовое использование
 * <ComponentName prop="value">
 *   Content
 * </ComponentName>
 * 
 * // Расширенное использование
 * <ComponentName
 *   variant="primary"
 *   size="lg"
 *   disabled={false}
 *   onClick={() => console.log('clicked')}
 * >
 *   Advanced Example
 * </ComponentName>
 * 
 * // Использование с другими компонентами
 * <ComponentName>
 *   <ChildComponent />
 * </ComponentName>
 * ```
 * 
 * @since 1.0.0
 */
const ComponentName = React.forwardRef<HTMLElement, ComponentProps>(
  ({ prop1, prop2, ...props }, ref) => {
    // Implementation
  }
);

Props интерфейсы​

/**
 * Props для компонента ComponentName
 */
export interface ComponentNameProps
  extends React.HTMLAttributes<HTMLElement> {
  /** 
   * Краткое описание пропа
   * Дополнительная информация о поведении или ограничениях
   * @default defaultValue
   */
  propName?: string;
  
  /** 
   * Обязательный проп с подробным описанием
   */
  requiredProp: number;
  
  /** 
   * Callback функция
   * @param value - Описание параметра
   * @returns Описание возвращаемого значения
   */
  onCallback?: (value: string) => void;
}

Варианты стилей (CVA)​

/**
 * Варианты стилей компонента ComponentName с использованием class-variance-authority
 */
const componentVariants = cva(
  "базовые классы",
  {
    variants: {
      variant: {
        /** Основной вариант для главных действий */
        primary: "классы для primary",
        /** Вторичный вариант для менее важных действий */
        secondary: "классы для secondary",
      },
      size: {
        /** Маленький размер для компактных интерфейсов */
        sm: "классы для sm",
        /** Средний размер (по умолчанию) */
        md: "классы для md",
      },
    },
    defaultVariants: {
      variant: "primary",
      size: "md",
    },
  }
);

🎣 Стандарты для хуков​

/**
 * Хук для [описание назначения]
 * 
 * Подробное описание функциональности хука,
 * когда и как его использовать.
 * 
 * Features:
 * - Список возможностей
 * - Оптимизации
 * - Обработка edge cases
 * 
 * @example
 * ```tsx
 * function Component() {
 *   const { value, setValue, reset } = useHookName(initialValue);
 *   
 *   return (
 *     <div>
 *       <span>{value}</span>
 *       <button onClick={() => setValue('new value')}>
 *         Update
 *       </button>
 *       <button onClick={reset}>Reset</button>
 *     </div>
 *   );
 * }
 * ```
 * 
 * @param initialValue - Начальное значение
 * @returns Объект с методами управления состоянием
 * @since 1.0.0
 */
function useHookName<T>(initialValue: T): HookReturnType<T> {
  // Implementation
}

🛠️ Стандарты для утилит​

/**
 * Краткое описание функции утилиты
 * 
 * Подробное описание алгоритма, логики работы
 * и случаев использования.
 * 
 * @example
 * ```typescript
 * // Простое использование
 * const result = utilityFunction('input');
 * 
 * // Сложное использование
 * const complexResult = utilityFunction(
 *   'input',
 *   { option: true }
 * );
 * ```
 * 
 * @param input - Описание входного параметра
 * @param options - Дополнительные опции (необязательно)
 * @returns Описание возвращаемого значения
 * @throws {Error} Когда возникает ошибка
 * @since 1.0.0
 */
function utilityFunction(
  input: string,
  options?: UtilityOptions
): UtilityResult {
  // Implementation
}

📝 Специальные теги​

@example - Примеры использования​

/**
 * @example
 * ```tsx
 * // Базовый пример
 * <Component />
 * 
 * // Расширенный пример
 * <Component
 *   prop="value"
 *   onEvent={() => {}}
 * />
 * ```
 */

@param - Параметры функций​

/**
 * @param name - Имя пользователя для отображения
 * @param options - Дополнительные настройки
 * @param options.showAvatar - Показывать ли аватар
 * @param options.size - Размер компонента
 */

@returns - Возвращаемые значения​

/**
 * @returns Объект с методами управления состоянием
 * @returns {boolean} true если операция успешна
 */

@throws - Исключения​

/**
 * @throws {Error} Когда передан некорректный параметр
 * @throws {ValidationError} При ошибке валидации
 */

@since - Версия добавления​

/**
 * @since 1.0.0 - Первая версия
 * @since 1.2.0 - Добавлена поддержка новых пропов
 */

@deprecated - Устаревшие элементы​

/**
 * @deprecated Используйте NewComponent вместо этого
 * @deprecated since 2.0.0 - Будет удален в версии 3.0.0
 */

@see - Ссылки на связанные элементы​

/**
 * @see {@link RelatedComponent} для похожей функциональности
 * @see {@link https://example.com} для дополнительной информации
 */

✅ Чек-лист качества документации​

Для компонентов:​

  • Краткое и понятное описание назначения
  • Список ключевых возможностей (Features)
  • Минимум 2-3 примера использования
  • Документация всех публичных пропов
  • Указание значений по умолчанию
  • Описание callback функций с параметрами

Для хуков:​

  • Описание назначения и случаев использования
  • Пример интеграции в компонент
  • Документация параметров и возвращаемых значений
  • Описание побочных эффектов

Для утилит:​

  • Описание алгоритма или логики
  • Примеры входных и выходных данных
  • Документация исключений
  • Указание сложности (если важно)

🚫 Что избегать​

❌ Плохие примеры:​

/**
 * Button component
 */
const Button = () => {}; // Слишком краткое описание

/**
 * This is a button that you can click
 * @param props - the props
 */
const Button = (props) => {}; // Бесполезное описание

/**
 * Компонент кнопки для нажатия мышкой или пальцем
 */
const Button = () => {}; // Слишком очевидное описание

✅ Хорошие примеры:​

/**
 * Универсальная кнопка с поддержкой различных вариантов оформления
 * 
 * Features:
 * - Множественные варианты (primary, secondary, outline)
 * - Состояние загрузки с индикатором
 * - Поддержка иконок до и после текста
 * - Полиморфный рендеринг через asChild
 * 
 * @example
 * ```tsx
 * <Button variant="primary" loading>
 *   Сохранить
 * </Button>
 * ```
 */

🔄 Процесс обновления документации​

  1. При добавлении компонента - Создать полную JSDoc документацию
  2. При изменении API - Обновить соответствующие комментарии
  3. При рефакторинге - Проверить актуальность примеров
  4. Перед релизом - Регенерировать документацию
# Проверка качества документации
npm run docs:generate
npm run docs:serve

Следование этим стандартам обеспечит высокое качество документации и упростит работу команды с кодовой базой.