Документация в TypeScript: как писать код, который говорит сам за себя

Введение: почему документация — это не скучная обязанность, а суперсила

Представьте: вы возвращаетесь к своему проекту через полгода. Открываете файл с логикой авторизации — и видите море кода на TypeScript. Типы есть, интерфейсы прописаны, но что делает эта функция? Почему параметр называется opts и какие у него поля? Знакомо?

Документация в TypeScript — это не просто «комментарии для галочки». Это инструмент, который превращает ваш код в понятную историю. Хорошая документация экономит часы дебаггинга, ускоряет онбординг новичков и делает ваш API дружелюбным. В этой статье мы разберём лучшие практики документирования TypeScript-проектов: от базовых комментариев JSDoc до продвинутой генерации документации с TypeDoc. Поехали!

1. JSDoc и TSDoc: фундамент вашей документации

TypeScript унаследовал от JavaScript популярный формат JSDoc, а затем сообщество разработало TSDoc — стандартизированный синтаксис для TypeScript. Если вы пишете библиотеку или API, TSDoc — ваш выбор. Он строже, лучше интегрируется с редакторами и генераторами документации.

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

Вот минимум, который стоит знать каждому разработчику:

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

/**
 * Вычисляет скидку на товар с учётом промокода.
 * 
 * @param price - Исходная цена товара (должна быть больше 0)
 * @param discountPercent - Процент скидки (от 0 до 100)
 * @param promoCode - Промокод, который может увеличить скидку
 * @returns Итоговая цена после применения скидки
 * @throws {Error} Если цена или процент некорректны
 * 
 * @example
 * // Пример: скидка 20% на товар за 1000 рублей
 * const finalPrice = calculateDiscount(1000, 20, 'SUMMER');
 * console.log(finalPrice); // 800
 */
function calculateDiscount(
  price: number,
  discountPercent: number,
  promoCode?: string
): number {
  if (price <= 0 || discountPercent < 0 || discountPercent > 100) {
    throw new Error('Некорректные параметры');
  }
  
  let discount = discountPercent;
  if (promoCode === 'SUMMER') {
    discount += 10; // дополнительная скидка
  }
  
  return price * (1 - discount / 100);
}

Совет: Всегда описывайте граничные случаи. Если параметр может быть undefined, укажите это в описании. TypeScript типы — это хорошо, но человеческий язык добавляет контекст.

2. Документируйте типы и интерфейсы

Одна из главных фич TypeScript — мощная система типов. Но даже самый строгий тип не объяснит назначение поля. Документируйте интерфейсы так же тщательно, как функции.

/**
 * Конфигурация для подключения к внешнему API погоды.
 */
interface WeatherApiConfig {
  /** Базовый URL API (например, https://api.weather.com) */
  baseUrl: string;
  
  /** Ключ аутентификации, полученный от провайдера */
  apiKey: string;
  
  /** 
   * Количество секунд ожидания ответа от сервера.
   * По умолчанию 5 секунд.
   */
  timeout?: number;
  
  /**
   * Версия API. Если не указана, используется последняя стабильная.
   * @deprecated Используйте поле `version` в URL
   */
  apiVersion?: string;
}

Обратите внимание: для timeout мы указали значение по умолчанию прямо в комментарии. Это избавляет разработчика от необходимости лезть в исходный код или тесты.

3. Генерация документации: превращаем комментарии в сайт

Писать комментарии — полдела. Нужно уметь превращать их в удобную документацию. Для TypeScript лучший инструмент — TypeDoc. Он парсит ваши TSDoc-комментарии и создаёт статический сайт с описанием всех типов, функций и классов.

Как настроить TypeDoc

Установка и базовый запуск:

npm install --save-dev typedoc

# Создать документацию в папке docs/
npx typedoc --out docs src/index.ts

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

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "exclude": ["**/__tests__/**"],
  "theme": "default",
  "includeVersion": true,
  "categorizeByGroup": true,
  "categoryOrder": ["Functions", "Types", "Interfaces", "*"]
}

Важно: TypeDoc поддерживает не только функции, но и модули, классы, перечисления. Добавьте в корневой файл проекта комментарий к модулю:

/**
 * @packageDocumentation
 * Модуль для работы с платежами.
 * Содержит функции для создания, обработки и отмены транзакций.
 */

4. Пишите README как продакт-менеджер

Документация в коде — это хорошо, но первое, что видит разработчик — README.md. Сделайте его информативным и структурированным. Вот чек-лист:

• Заголовок и описание: одной строкой объясните, что делает проект.
• Установка: команды для npm/yarn/pnpm.
• Быстрый старт: минимальный рабочий пример.
• API Reference: ссылка на сгенерированную документацию.
• Примеры: 2-3 реальных сценария использования.
• Contributing: как помочь проекту.

Пример хорошего начала README:

# Weather SDK — TypeScript клиент для OpenWeatherMap

Простая и типобезопасная библиотека для получения данных о погоде.
Поддерживает текущую погоду, прогноз на 5 дней и исторические данные.

## Установка

```bash
npm install @myorg/weather-sdk
```

## Быстрый старт

```typescript
import { WeatherClient } from '@myorg/weather-sdk';

const client = new WeatherClient({ apiKey: 'YOUR_KEY' });
const weather = await client.getCurrentWeather('Moscow');
console.log(weather.temperature); // number
```

5. Документирование сложных сценариев: перегрузки функций и дженерики

TypeScript позволяет создавать перегруженные функции и дженерики. Документировать их нужно особенно тщательно, иначе пользователь запутается.

Перегрузки функций

/**
 * Создаёт пользователя в системе.
 * 
 * @param name - Имя пользователя (обязательно)
 * @param email - Email (обязательно)
 * @returns Объект пользователя