JSDoc для JavaScript: документирование кода

Ноутбук с кодом JavaScript на экране, стоящий на столе у окна

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

Хорошая документация полезна для всех, кто работает с кодом: коллег, ревьюеров и вас самих через несколько месяцев. Она объясняет, почему выбран определённый подход, как пользоваться функцией или API, и какие ограничения у кода.

Для JavaScript-разработчиков JSDoc — простой и надёжный способ начать документировать проект.

Что такое JSDoc?

JSDoc — это инструмент «docs as code»: он генерирует HTML-документацию, читая специальные комментарии в исходниках JavaScript. Подобно GoDoc в Go, JSDoc превращает пометки в файлах в удобный набор страниц.

Плюсы JSDoc:

Документация живёт рядом с кодом и обновляется вместе с ним.
Генерация автоматическая — меньше рутинной работы.
Поддерживает теги для типов, примеров и ошибок.

Коротко: JSDoc парсит /* … /-комментарии и формирует читаемый HTML.

Установка JSDoc

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

npm install --save-dev jsdoc

После установки JSDoc доступен для локального запуска через npx или как npm-скрипт.

Important: ставьте JSDoc в devDependencies, чтобы он не попадал в production-бандл.

Как писать комментарии JSDoc

JSDoc использует много специальных тегов. Комментарии пишут внутри блоков /* / перед функциями, классами и модулями.

Пример простого комментария:

/**
 * Получает пользователя по имени.
 * @param {string} name - Имя пользователя
 * @returns {string} Пользователь
 */
function getUser(name) {
  const User = name;
  return User;
}

Основные теги, которые вы будете использовать чаще всего:

@param — описание параметра и его тип.
@returns или @return — тип и описание возвращаемого значения.
@throws — описывает возможные исключения.
@example — показывает пример использования.
@module — помечает модуль.
@typedef — объявляет сложные пользовательские типы.

Чтобы сгенерировать документацию для файла, выполните:

npx jsdoc src/main.js

Если JSDoc установлен глобально, можно запустить просто:

jsdoc path/to/file.js

Команда создаст папку out в корне проекта с HTML-страницами. Откройте out/index.html в браузере или запустите локальный сервер, чтобы просмотреть результат.

Скриншот страницы, сгенерированной JSDoc, показывающий список методов и описание

Конфигурация вывода JSDoc

Чтобы изменить поведение по умолчанию, создайте файл конфигурации, например conf.js, и экспортируйте модуль с настройками.

Пример conf.js:

module.exports = {
  source: {
    includePattern: ".+\\.js(doc|x)?$",
    excludePattern: ["node_modules"],
  },
  recurseDepth: 5,
  sourceType: "module",
  opts: {
    template: "path/to/template",
    destination: "./docs/",
    recurse: true,
  },
};

Ключевые параметры:

includePattern / excludePattern — какие файлы включать/исключать.
recurseDepth — насколько глубоко спускаться по папкам.
template — путь к шаблону оформления.
destination — папка для результатов.

Запуск с конфигом:

jsdoc -c /path/to/conf.js

Чтобы упростить запуск, добавьте команду в package.json в секцию scripts:

"scripts": {
  "dev": "nodemon app.js",
  "run-docs": "jsdoc -c /path/to/conf.js"
},

Теперь документацию можно генерировать командой npm run run-docs.

Пример библиотеки с JSDoc

Ниже — простая библиотека с методами add и subtract и хорошими JSDoc-комментариями.

/**
 * Библиотека для базовых арифметических операций.
 * @module arithmetic
 */
module.exports = {
    /**
     * Складывает два числа.
     * @param {number} a - Первое число.
     * @param {number} b - Второе число.
     * @return {number} Сумма чисел.
     * @throws {TypeError} Если любой аргумент не число.
     * @example
     * const arithmetic = require('arithmetic');
     * const sum = arithmetic.add(5, 10);
     * console.log(sum); // 15
     */
    add: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a + b;
    },

    /**
     * Вычитает второе число из первого.
     * @param {number} a - Число, из которого вычитают.
     * @param {number} b - Число, которое вычитают.
     * @return {number} Результат вычитания.
     * @throws {TypeError} Если любой аргумент не число.
     * @example
     * const arithmetic = require('arithmetic');
     * const difference = arithmetic.subtract(10, 5);
     * console.log(difference); // 5
     */
    subtract: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a - b;
    }

    // ... другие методы ...
};

Комментарии в примере демонстрируют:

Описание модуля и метода.
Параметры с типами и пояснениями.
Возвращаемое значение и его тип.
Исключения и условия их выброса.
Пример использования.

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

Короткие правила для качественной документации:

Пишите комментарии, которые объясняют «почему», а не только «что». Код уже показывает что.
Используйте @example для реальных сценариев использования.
Обновляйте комментарии одновременно с изменением кода.
Не дублируйте очевидное: простая функция add(a, b) не нуждается в длинном описании.
Определяйте общие типы через @typedef.

Important: не храните в комментариях чувствительные данные (пароли, ключи, личные данные).

Когда JSDoc не подходит

Примеры ситуаций, где JSDoc может быть ограничен:

Проекты, активно использующие TypeScript — там статические типы и TSDoc часто предпочтительнее.
Сложные API, которые требуют интерактивной документации (Swagger/OpenAPI для HTTP API).
Генерация документации из других артефактов (BDD-спецификации или UML).

Альтернативы и дополнения:

TypeScript + TSDoc: интеграция типов делает документацию более строгой.
Swagger/OpenAPI: для REST/HTTP API удобнее интерактивная документация.
Storybook: для документирования UI-компонентов.

Практическая методология документирования (мини‑метод)

Комментируйте интерфейсы: функции, модули, объекты, публичные классы.
Добавьте примеры использования для каждого публичного API.
Пересмотрите комментарии при изменении API в процессе code review.

Эта простая схема помогает поддерживать документацию актуальной.

Чек-листы по ролям

Разработчик:

Добавил JSDoc для новых публичных функций.
Указал типы и описал крайние случаи.
Добавил @example для необычных сценариев.

Ревьюер:

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

Поддерживающий (maintainer):

Обновил конфигурацию шаблонов и путь назначения.
Сгенерировал документацию перед релизом.
Проверил ссылочную целостность (нет битых ссылок в сгенерированном HTML).

Чек-лист качества документации

Документация генерируется без ошибок.
Все публичные методы имеют @param и @return.
Примеры покрывают распространённые сценарии.
Исключения задокументированы (@throws).
Структура модулей отражена в навигации HTML.

Шпаргалка по тегам JSDoc

@param {type} name - описание
@returns {type} описание
@throws {TypeError} описание
@example код
@module имя
@typedef {Object} Name
@property {type} prop - описание

Decision flow: стоит ли внедрять JSDoc

flowchart TD
  A[Нужна внутренняя документация?] -->|Да| B{Проект на TypeScript?}
  B -->|Да| C[Использовать TSDoc + автогенерацию типов]
  B -->|Нет| D[Использовать JSDoc]
  A -->|Нет| E[Документация не требуется сейчас]

Критерии приёмки

Комментарии покрывают все публичные интерфейсы.
npm run run-docs успешно генерирует HTML без предупреждений.
Примеры в документации запускаются и дают ожидаемый результат.
Конфигурация conf.js включена в репозиторий и документирована в README.

Тесты и проверки

Интеграционный тест: CI запускает генерацию JSDoc и проверяет, что выходной каталог не пуст.
Smoke-test: открыть out/index.html и убедиться, что основные разделы видимы.
Примеры: простые unit-тесты для кусков, показанных в @example.

Безопасность и приватность

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

Короткое руководство по миграции на JSDoc

Добавьте jsdoc в devDependencies.
Пропишите базовый conf.js с includePattern и destination.
Начните с документирования публичных модулей.
Добавьте npm-скрипт и интегрируйте генерацию в CI/CD.

Частые ошибки и как их избежать

Писать комментарии, которые противоречат коду — обновляйте вместе с изменениями.
Дублировать очевидные вещи — фокусируйтесь на поведении и ограничениях.
Оставлять ненужные @todo в комментариях — используйте issue-трекер.

Заключение

JSDoc — быстрый путь к автоматической документации JavaScript-проекта. Он хорош для поддерживаемых кодовых баз, помогает новым участникам и делает код понятнее для всех. Сочетайте JSDoc с проверками в CI, шаблонами и стандартизированными практиками документирования, чтобы получить максимальную пользу.

Выводы:

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

Summary:

JSDoc хранит документацию рядом с кодом.
Конфигурируется через conf.js и npm-скрипты.
Подходит не для всех случаев (TypeScript, интерактивные API).

Notes: Если проект на TypeScript или вам нужна интерактивность для HTTP API, рассмотрите TSDoc или OpenAPI.

Документирование JavaScript с помощью JSDoc