• Не про комментарии, а про описание интерфейсов и API
• Повышает читаемость и сопровождение
• Улучшает работу команды и вхождение в проект
• Используется IDE и автокомплитом

• Назначение модуля/функции
• Типы входных и выходных данных
• Примеры использования
• Указание особенностей или ограничений

• Функции: глаголы (getUser, calculateTotal)
• Модули: предметная область (authService, logger)
• Переменные:
  • булевы: isValid, hasPermission
  • коллекции: users, items
  • константы: MAX_LENGTH, DEFAULT_TIMEOUT

• JSDoc — способ аннотировать JS-код для понимания структуры и типов
• Не требует TypeScript!
• Работает в любом .js файле

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

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

• Подсказки и типы при наведении
• Автокомплит параметров и возвращаемых значений
• Можно использовать без TS!

JSDoc:

/** @param {string} name */
function greet(name) {
  return "Hi, " + name;
}

TypeScript:

function greet(name: string): string {
  return "Hi, " + name;
}

• .js + JSDoc + tsconfig.json
• Получаем линтинг и автотипизацию без перехода на .ts

npm install --save-dev jsdoc
npx jsdoc src -r -d docs

• Генерирует HTML-документацию по комментариям

npm install --save-dev typedoc
npx typedoc src

• Создаёт красивую документацию с ссылками между типами и интерфейсами

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": true
  },
  "include": ["src"]
}

• TypeScript проверяет .js файлы
• Учитывает типы из JSDoc
• Показывает ошибки типов до выполнения

/** @param {number} x */
function double(x) {
  return x * "2"; // ❌ ошибка типов
}

• Документация = ясное API, а не просто комментарии
• JSDoc помогает даже без TypeScript
• TS усиливает надёжность и масштабируемость
• Документацию можно генерировать автоматически
• TypeScript умеет проверять .js-файлы с JSDoc