Документация TypeScript: продвинутые техники и инструменты

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Написание документации для TypeScript проекта: продвинутый уровень

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

1. Продвинутое использование JSDoc и TypeDoc

JSDoc — это стандарт аннотаций, который TypeScript отлично поддерживает. На продвинутом уровне важно не просто описывать параметры, а использовать все возможности системы тегов.

1.1. Теги для сложных типов

Используйте @template для описания дженериков, @typeParam для уточнения параметров типа и @callback для определения сигнатур функций обратного вызова.

/**
 * Универсальная функция для получения значения из хранилища.
 *
 * @template T - Тип возвращаемого значения.
 * @param key - Ключ для поиска.
 * @returns Значение типа T или undefined, если ключ не найден.
 */
function getValue<T>(key: string): T | undefined {
    // реализация
}

/**
 * @callback FetchCallback
 * @param data - Полученные данные.
 * @param error - Ошибка, если произошла.
 * @returns void
 */
type FetchCallback<T> = (data: T, error?: Error) => void;

1.2. Документирование перегрузок функций

TypeScript позволяет перегружать функции. В документации нужно описать каждую перегрузку отдельно.

/**
 * Создает строку из чисел.
 * @param a - Первое число.
 * @param b - Второе число.
 * @returns Строка, объединяющая числа.
 */
function combine(a: number, b: number): string;
/**
 * Создает строку из строк.
 * @param a - Первая строка.
 * @param b - Вторая строка.
 * @returns Объединенная строка.
 */
function combine(a: string, b: string): string;
function combine(a: any, b: any): string {
    return `${a}${b}`;
}

1.3. Кастомные модификаторы TypeDoc

TypeDoc (основной генератор для TypeScript) поддерживает кастомные теги, которые можно настраивать через файл конфигурации typedoc.json.

// typedoc.json
{
  "blockTags": ["@example", "@since", "@deprecated"],
  "modifierTags": ["@internal", "@public", "@experimental"]
}

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

/**
 * Выполняет HTTP-запрос.
 *
 * @since 2.1.0
 * @experimental - API может измениться в будущем.
 * @example
 * ```typescript
 * const result = await httpRequest('https://api.example.com');
 * ```
 */
async function httpRequest(url: string): Promise<Response> {
    // ...
}

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

Продвинутая документация должна описывать не только функции, но и сложные структуры данных, особенно если они используются в нескольких местах.

2.1. Условные типы и маппинг

Документируйте условные типы так, чтобы разработчик понимал, как они работают.

/**
 * Извлекает тип элементов массива.
 * @template T - Тип массива.
 */
type ArrayElement<T> = T extends (infer U)[] ? U : never;

/**
 * Делает все свойства объекта опциональными (Partial).
 * @template T - Исходный тип объекта.
 */
type DeepPartial<T> = {
    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

2.2. Документирование дискриминированных объединений

Дискриминированные объединения (discriminated unions) — мощная особенность TypeScript. В документации нужно явно указать общее поле-дискриминатор.

/**
 * Состояние запроса.
 * @discriminator status
 */
type RequestState<T> =
    | { status: 'idle'; }
    | { status: 'loading'; }
    | { status: 'success'; data: T; }
    | { status: 'error'; error: Error; };

TypeDoc автоматически сгенерирует диаграмму состояний, если включена опция --plugin typedoc-plugin-mermaid.

3. Автоматическая генерация документации и CI/CD

На продвинутом уровне документация должна генерироваться автоматически и быть частью пайплайна разработки.

3.1. Настройка TypeDoc

Установите TypeDoc и настройте его для генерации статического сайта.

npm install typedoc --save-dev

Создайте скрипт в package.json:

{
  "scripts": {
    "docs": "typedoc --out docs src/index.ts",
    "docs:watch": "typedoc --watch --out docs src/index.ts"
  }
}

Пример конфигурации typedoc.json для продвинутого проекта:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeExternals": true,
  "includeVersion": true,
  "categorizeByGroup": true,
  "categoryOrder": ["Основные функции", "Утилиты", "Типы", "Интерфейсы"],
  "plugin": ["typedoc-plugin-mermaid", "typedoc-plugin-rename-defaults"]
}

3.2. Интеграция с CI/CD (GitHub Actions)

Добавьте Workflow для автоматической публикации документации на GitHub Pages.

name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
      - name: Generate docs
        run: npm run docs
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs