TypeDoc для TypeScript: полное руководство с примерами

Что такое TypeDoc и зачем он нужен?

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

Зачем он нужен? В современной разработке документация — это не роскошь, а необходимость. TypeDoc решает несколько ключевых задач:

• Автоматизация: Вам не нужно вручную писать документацию. Достаточно добавить комментарии к функциям, классам, интерфейсам и типам, и TypeDoc сгенерирует готовый сайт.
• Актуальность: Документация всегда соответствует коду, так как генерируется непосредственно из него.
• Навигация: TypeDoc создаёт удобную навигацию по проекту: древовидную структуру, поиск, ссылки на типы.
• Поддержка TypeScript: Он понимает сложные типы TypeScript: дженерики, утилитарные типы, перегрузки функций, модули и пространства имён.
• Расширяемость: TypeDoc поддерживает темы, плагины и кастомизацию.

TypeDoc идеально подходит для:

• Библиотек и пакетов, распространяемых через npm.
• Внутренних проектов, где нужно быстро познакомить новых разработчиков с кодом.
• API-документации для серверных приложений на TypeScript.
• Образовательных проектов, где важна наглядность.

Установка TypeDoc

TypeDoc устанавливается через npm (Node Package Manager). Убедитесь, что у вас установлен Node.js (версия 14 или выше).

Самый простой способ — установить TypeDoc глобально:

npm install -g typedoc

Однако для проектов рекомендуется устанавливать его как локальную зависимость разработки:

npm install --save-dev typedoc

После установки вы можете проверить версию:

npx typedoc --version

Если вы используете Yarn:

yarn add -D typedoc

Для pnpm:

pnpm add -D typedoc

Быстрый старт с примером кода

Давайте создадим простой проект и сгенерируем для него документацию.

Шаг 1: Создайте проект

mkdir my-typedoc-project
cd my-typedoc-project
npm init -y

Шаг 2: Установите TypeDoc

npm install --save-dev typedoc

Шаг 3: Создайте файл с кодом src/index.ts

/**
 * Модуль для работы с математическими операциями.
 * @module MathUtils
 */

/**
 * Складывает два числа.
 * @param a - Первое число
 * @param b - Второе число
 * @returns Сумма a и b
 * @example
 * ```typescript
 * const result = add(2, 3);
 * console.log(result); // 5
 * ```
 */
export function add(a: number, b: number): number {
    return a + b;
}

/**
 * Вычитает второе число из первого.
 * @param a - Уменьшаемое
 * @param b - Вычитаемое
 * @returns Разность a и b
 */
export function subtract(a: number, b: number): number {
    return a - b;
}

/**
 * Интерфейс для представления точки в двумерном пространстве.
 */
export interface Point {
    /** Координата X */
    x: number;
    /** Координата Y */
    y: number;
}

/**
 * Вычисляет расстояние между двумя точками.
 * @param p1 - Первая точка
 * @param p2 - Вторая точка
 * @returns Расстояние между точками
 */
export function distance(p1: Point, p2: Point): number {
    const dx = p2.x - p1.x;
    const dy = p2.y - p1.y;
    return Math.sqrt(dx * dx + dy * dy);
}

Шаг 4: Сгенерируйте документацию

npx typedoc src/index.ts

По умолчанию TypeDoc создаст папку docs с HTML-файлами. Откройте docs/index.html в браузере, и вы увидите красивую документацию.

Шаг 5: Настройка через tsconfig.json

Добавьте в package.json скрипт для генерации:

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

Теперь можно запускать:

npm run docs

Основные методы и функции TypeDoc

TypeDoc — это не библиотека с методами, а инструмент командной строки. Однако у него есть множество опций и конфигураций. Рассмотрим 10 самых важных.

1. --out (или -o)

Что делает: Указывает директорию для вывода сгенерированной документации.

Параметры: Путь к папке (строка).

Пример:

typedoc --out ./documentation src/index.ts

Создаст папку documentation в текущей директории.

2. --entryPoints (или --entryPoint)

Что делает: Определяет точки входа для анализа. Можно указать несколько файлов или директорий.

Параметры: Один или несколько путей к файлам/папкам.

Пример:

typedoc --entryPoints src/index.ts --entryPoints src/utils.ts

3. --tsconfig

Что делает: Указывает путь к файлу tsconfig.json. TypeDoc использует его для настройки компилятора TypeScript.

Параметры: Путь к файлу (строка).

Пример:

typedoc --tsconfig ./tsconfig.build.json src/index.ts

4. --name

Что делает: Задаёт название проекта, которое отображается в заголовке документации.

Параметры: Строка.

Пример:

typedoc --name "My Awesome Library" src/index.ts

5. --theme

Что делает: Выбирает тему оформления. По умолчанию используется default. Есть также minimal и кастомные темы.

Параметры: Название темы (строка) или путь к кастомной теме.

Пример:

typedoc --theme minimal src/index.ts

6. --includeVersion

Что делает: Добавляет номер версии проекта (из package.json) в заголовок документации.

Параметры: Флаг (без значения).

Пример:

typedoc --includeVersion src/index.ts

7. --exclude

Что делает: Исключает файлы или папки из генерации документации. Поддерживает glob-паттерны.

Параметры: Паттерн (строка).

Пример:

typedoc --exclude "**/*.test.ts" src/index.ts

8. --excludePrivate

Что делает: Исключает из документации приватные члены классов (с модификатором private).

Параметры: Флаг (без значения).

Пример:

typedoc --excludePrivate src/index.ts

9. --excludeProtected

Что делает: Исключает из документации защищённые члены классов (с модификатором protected).

Параметры: Флаг (без значения).

Пример:

typedoc --excludeProtected src/index.ts

10. --plugin

Что делает: Подключает плагины для расширения функциональности TypeDoc.

Параметры: Название плагина или путь к нему.

Пример:

typedoc --plugin typedoc-plugin-markdown src/index.ts

Этот плагин генерирует документацию в формате Markdown вместо HTML.

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

Представим, что вы разрабатываете библиотеку для работы с пользователями. Вот как может выглядеть ваш проект и его документирование.

Структура проекта:

user-lib/
├── src/
│   ├── index.ts
│   ├── user.ts
│   └── utils.ts
├── package.json
└── tsconfig.json

src/user.ts

/**
 * Модуль для работы с пользователями.
 * @module UserModule
 */

/**
 * Интерфейс, описывающий пользователя.
 */
export interface User {
    /** Уникальный идентификатор */
    id: number;
    /** Имя пользователя */
    name: string;
    /** Email пользователя */
    email: string;
    /** Флаг активности */
    isActive: boolean;
}

/**
 * Класс для управления пользователями.
 */
export class UserManager {
    private users: User[] = [];

    /**
     * Добавляет нового пользователя.
     * @param user - Объект пользователя (без id)
     * @returns Созданный пользователь с присвоенным id
     */
    addUser(user: Omit<User, 'id'>): User {
        const newUser: User = {
            id: this.users.length + 1,
            ...user
        };
        this.users.push(newUser);
        return newUser;
    }

    /**
     * Находит пользователя по ID.
     * @param id - ID пользователя
     * @returns Пользователь или undefined, если не найден
     */
    findById(id: number): User | undefined {
        return this.users.find(u => u.id === id);
    }

    /**
     * Возвращает список всех активных пользователей.
     * @returns Массив активных пользователей
     */
    getActiveUsers(): User[] {
        return this.users.filter(u => u.isActive);
    }

    /**
     * Удаляет пользователя по ID.
     * @param id - ID пользователя для удаления
     * @returns true, если пользователь был удалён, иначе false
     */
    deleteUser(id: number): boolean {
        const index = this.users.findIndex(u => u.id === id);
        if (index !== -1) {
            this.users.splice(index, 1);
            return true;
        }
        return false;
    }
}

src/utils.ts

/**
 * Модуль вспомогательных функций.
 * @module Utils
 */

/**
 * Проверяет, является ли строка валидным email.
 * @param email - Строка для проверки
 * @returns true, если email валидный
 */
export function isValidEmail(email: string): boolean {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(email);
}

/**
 * Генерирует случайный ID для пользователя.
 * @returns Случайное число от 1 до 10000
 */
export function generateRandomId(): number {
    return Math.floor(Math.random() * 10000) + 1;
}

src/index.ts

/**
 * Библиотека для управления пользователями.
 * @packageDocumentation
 */

export { User, UserManager } from './user';
export { isValidEmail, generate