Документирование компонентов

Haunted — это библиотека для создания веб-компонентов на базе современных возможностей JavaScript, особенно хуков, вдохновлённых React. Документирование компонентов в Haunted важно для поддерживаемости кода, масштабируемости и удобства совместной работы в командах. Правильное документирование позволяет быстро понимать назначение компонентов, их API и взаимодействие с другими частями приложения.

Комментарии JSDoc

Haunted использует обычные возможности JavaScript, поэтому стандартный способ документирования — это JSDoc. Основные элементы:

/**
 * Компонент кнопки с кастомными стилями и событием клика.
 *
 * @param {Object} props - Свойства компонента.
 * @param {string} props.label - Текст кнопки.
 * @param {Function} [props.onClick] - Колбэк при клике.
 */
function Button({ label, onClick }) {
  return html`<button @click=${onClick}>${label}</button>`;
}

Ключевые моменты:

@param описывает входные свойства (props). Указание типа повышает удобство использования в IDE.
[props.onClick] — квадратные скобки обозначают необязательный параметр.
Комментарий располагается непосредственно перед объявлением функции или компонента.

Документирование хуков

Haunted поддерживает хуки, аналогичные React, такие как useState, useEffect, useReducer. Для каждого пользовательского хука рекомендуется добавлять описание, объясняющее его назначение и возвращаемое значение:

/**
 * Хук для управления состоянием счётчика.
 *
 * @param {number} initialValue - Начальное значение счётчика.
 * @returns {[number, Function]} Массив с текущим значением и функцией увеличения.
 */
function useCounter(initialValue = 0) {
  const [count, setCount] = useState(initialValue);
  const increment = () => setCount(c => c + 1);
  return [count, increment];
}

Особенности:

Указываются типы входных и выходных данных.
Описание функций и колбэков улучшает читаемость и позволяет использовать автоматическую генерацию документации.

Документирование событий

Компоненты Haunted часто взаимодействуют с внешним миром через пользовательские события (CustomEvent). В документации стоит фиксировать:

Название события
Данные, передаваемые в событии

/**
 * Компонент формы, который испускает событие submit.
 *
 * @event submit
 * @type {CustomEvent<{value: string}>}
 */
function MyForm() {
  const handleSubmit = e => {
    e.preventDefault();
    const value = e.target.elements.input.value;
    dispatchEvent(new CustomEvent('submit', { detail: { value } }));
  };
  return html`
    <form @submit=${handleSubmit}>
      <input name="input" />
      <button type="submit">Отправить</button>
    </form>
  `;
}

Рекомендации:

Всегда указывать тип данных, передаваемых через detail.
Описывать цель события, чтобы другие разработчики понимали, когда и как его использовать.

Документирование CSS и стилей

Haunted позволяет инкапсулировать стили внутри компонентов с помощью шаблонных литералов:

const style = html`
  <style>
    button {
      background-color: blue;
      color: white;
      padding: 0.5em 1em;
    }
  </style>
`;

Документирование стилей важно для понимания взаимодействия с DOM:

Указывать, какие классы или элементы изменяются.
Фиксировать зависимости, например переменные CSS, если используются кастомные свойства.

Примеры использования компонентов

Наличие примеров в документации повышает практическую ценность. Для Haunted рекомендуется показывать:

Создание экземпляра компонента
Передачу свойств (props)
Обработку событий

/**
 * Пример использования компонента Button
 */
const button = document.createElement('my-button');
button.label = 'Нажми меня';
button.addEventListener('click', () => console.log('Клик!'));
document.body.appendChild(button);

Автоматическая генерация документации

С помощью инструментов типа TypeDoc или JSDoc можно автоматически создавать веб-документацию по компонентам Haunted. Рекомендуется:

Поддерживать строгую типизацию через JSDoc
Комментарии размещать сразу перед функциями и хуками
Использовать теги @param, @returns, @event и @typedef для сложных структур данных

Пример для сложного props-объекта:

/**
 * @typedef {Object} CardProps
 * @property {string} title - Заголовок карточки.
 * @property {string} content - Основной текст.
 * @property {boolean} [highlighted] - Выделение карточки.
 */

Использование @typedef повышает читаемость и позволяет IDE автоматически подсказывать свойства объекта.