Написание документации для TypeScript проекта: от А до Я

Введение: зачем нужна документация в TypeScript проектах

Качественная документация — это не просто приятный бонус, а критически важный элемент любого профессионального TypeScript проекта. Она служит мостом между разработчиками, облегчает онбординг новых членов команды и помогает избежать ошибок при использовании API. TypeScript, с его мощной системой типов, предоставляет уникальные возможности для генерации точной и самодокументируемой документации. В этой статье мы разберём полный процесс: от написания комментариев в коде до публикации готовой документации.

Основы: JSDoc и аннотации для TypeScript

TypeScript поддерживает синтаксис JSDoc, что позволяет добавлять структурированные комментарии непосредственно в код. Это основа для создания документации, понятной как человеку, так и инструментам.

Базовые теги JSDoc

Начнём с простого примера функции, которая складывает два числа:

/**
 * Складывает два числа.
 * @param a - Первое слагаемое.
 * @param b - Второе слагаемое.
 * @returns Сумма двух чисел.
 */
function add(a: number, b: number): number {
    return a + b;
}

Ключевые теги:

• @param — описывает аргумент функции. Рекомендуется указывать тип и назначение.
• @returns — описывает возвращаемое значение.
• @throws — указывает, какие исключения может выбрасывать функция.
• @example — показывает пример использования.

Документирование сложных типов

Для интерфейсов и типов используйте @property или описывайте поля внутри блока:

interface UserConfig {
    /** Имя пользователя */
    name: string;
    /** Возраст пользователя (опционально) */
    age?: number;
    /** Роль в системе */
    role: 'admin' | 'user';
}

/**
 * Создаёт конфигурацию пользователя.
 * @param config - Объект с настройками пользователя.
 * @returns Объект конфигурации.
 */
function createUser(config: UserConfig): UserConfig {
    return config;
}

Используйте @template для дженериков:

/**
 * Обёртка для хранения значения.
 * @template T - Тип хранимого значения.
 */
class Box<T> {
    /** Хранимое значение */
    value: T;
    constructor(value: T) {
        this.value = value;
    }
}

Инструменты для генерации документации: TypeDoc

TypeDoc — это основной инструмент для автоматической генерации документации из JSDoc-аннотаций в TypeScript. Он создаёт статический HTML-сайт с удобной навигацией.

Установка и настройка

Установите TypeDoc как dev-зависимость:

npm install --save-dev typedoc

Создайте конфигурационный файл typedoc.json в корне проекта:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "theme": "default",
  "excludePrivate": true,
  "excludeProtected": false,
  "includeVersion": true,
  "categorizeByGroup": true
}

Параметры конфигурации:

• entryPoints — точка входа в ваш проект (обычно главный файл экспорта).
• out — папка, куда будет сгенерирована документация.
• excludePrivate — скрыть приватные члены классов.
• includeVersion — добавить версию проекта в документацию.

Запуск генерации

Добавьте скрипт в package.json:

{
  "scripts": {
    "docs:generate": "typedoc"
  }
}

Выполните команду:

npm run docs:generate

После этого в папке docs появится статический сайт. Откройте docs/index.html в браузере.

Лучшие практики написания документации

Чтобы документация была полезной, следуйте нескольким правилам.

1. Пишите комментарии для людей, а не для машин

Избегайте очевидных описаний. Вместо // Устанавливаем значение напишите // Устанавливаем значение таймера ожидания в миллисекундах. Комментарий должен отвечать на вопрос «почему?», а не «что?».

2. Документируйте публичное API

Все экспортируемые функции, классы и интерфейсы должны иметь JSDoc. Внутренние (приватные) функции можно документировать по необходимости.

3. Используйте @example для сложных сценариев

Пример кода — лучший способ объяснить, как работает функция:

/**
 * Форматирует дату в строку.
 * @param date - Объект Date.
 * @param format - Формат строки (например, 'YYYY-MM-DD').
 * @returns Отформатированная строка.
 * @example
 * // returns '2023-10-05'
 * formatDate(new Date(2023, 9, 5), 'YYYY-MM-DD');
 */
function formatDate(date: Date, format: string): string {
    // реализация
}

4. Поддерживайте документацию в актуальном состоянии

Документация должна обновляться вместе с кодом. Используйте CI/CD для автоматической перегенерации документации при каждом пуше в основную ветку. Пример конфигурации для GitHub Actions:

name: Generate Docs
on:
  push:
    branches: [main]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run docs:generate
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Заключение

Написание документации для TypeScript проекта — это инвестиция, которая окупается многократно. Используя JSDoc для аннотаций и TypeDoc для генерации, вы создаёте прозрачную и удобную документацию, которая всегда синхронизирована с кодом. Начните с малого: добавьте JSDoc к основным функциям и настройте TypeDoc. Со временем это станет привычкой, а ваш проект — примером для подражания в команде.

Помните: хорошая документация не только объясняет, как работает код,