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

Ноутбук на столе перед окном с экраном, показывающим JavaScript-код.

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

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

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

Что такое JSDoc?

Документирование кода может быть сложным и рутинным. Однако всё больше команд применяют подход «документы как код» (docs as code), и многие языки имеют библиотеки, которые автоматизируют процесс. Так же как в Go существует GoDoc для генерации документации из кода, в JavaScript есть JSDoc.

JSDoc интерпретирует специальные комментарии в исходниках JavaScript, обрабатывает их и генерирует готовую документацию в HTML. Это позволяет хранить описание прямо в кодовой базе: обновили код — проще обновить документацию.

Установка JSDoc

Создатели JSDoc упростили запуск и интеграцию в проект.

Чтобы установить JSDoc локально как dev-зависимость, выполните:

npm install --save-dev jsdoc

Это добавит библиотеку в ваш проект как devDependency.

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

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

Пример:

/**  
 * Gets User by name.  
 * @param {string} name - The name of the User  
 * @returns {string} User  
 */  
  
function getUser(name) {  
  const User = name;  
  return User;  
}

Теги @param и @returns — лишь часть возможных ключевых слов JSDoc.

Чтобы сгенерировать документацию для этого файла, выполните команду npx jsdoc с путём к файлу JavaScript.

npx jsdoc src/main.js

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

jsdoc path/to/file.js

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

Скриншот страницы сгенерированной документации JSDoc.

Настройка вывода JSDoc

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

Создайте файл 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,  
  },  
};

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

Чтобы изменить расположение сгенерированной документации, укажите в destination нужную директорию (в примере — папка docs в корне проекта).

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

jsdoc -c /path/to/conf.js

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

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

После этого команда npm run run-docs будет генерировать документацию по указанной конфигурации.

Пример документации, сгенерированной JSDoc

Ниже — простая библиотека арифметики с методами add и subtract. Это пример хорошо документированного JavaScript-кода:

/**  
 * A library for performing basic arithmetic operations.  
 * @module arithmetic  
 */  
module.exports = {  
    /**  
     * Adds two numbers.  
     * @param {number} a - The first number.  
     * @param {number} b - The second number.  
     * @return {number} The sum of the two numbers.  
     * @throws {TypeError} If any of the arguments is not a number.  
     *   
     * @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;  
    },  
  
    /**  
     * Subtracts the second number from the first number.  
     * @param {number} a - The number to subtract from.  
     * @param {number} b - The number to subtract.  
     * @return {number} The result of the subtraction.  
     * @throws {TypeError} If any of the arguments is not a number.  
     *   
     * @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;  
    }  
  
    // ... other methods ...  
};

Комментарии JSDoc в этом примере содержат:

Описание модуля и его назначения.
Параметры методов с указанием типа и краткого описания.
Значение и тип, возвращаемые методом.
Ошибки, которые может выбросить метод, и условия их возникновения.
Примеры использования (@example).
Тег @module для указания модуля.

Когда JSDoc может не подойти

Для строго типизированных проектов TypeScript часто предпочтительнее, потому что типы содержатся прямо в коде и дают более строгую проверку на этапе компиляции.
Если нужен полный API-портал с интерактивными примерами и версиями методов, имеет смысл рассмотреть OpenAPI/Swagger для HTTP API или отдельные инструменты для генерации статических сайтов документации.
Для очень динамичного кода (например, метапрограммирование) JSDoc может не корректно отражать поведение, и тогда потребуется вручную дополнять документацию.

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

TypeScript — типы и документация в одном файле; хорошо для крупных кодовых баз.
Swagger / OpenAPI — если вы документируете HTTP API.
Storybook — для документирования UI-компонентов.
Документация в виде Wiki или MD-файлы в репозитории — когда нужен широкий контекст и руководство по эксплуатации.

Мини-методология внедрения JSDoc в команду

Начните с документации публичного API (модули, функции, экспортируемые классы).
Включите правило в Code Review: новые публичные изменения должны сопровождаться обновлёнными JSDoc-комментариями.
Добавьте npm-скрипт для генерации документации и шаг в CI, который проверяет, что документация успешно собирается.
Выберите шаблон оформления и включите его в конфиг conf.js.
Назначьте владельца документации для релизов и регулярных ревью.

Чеклист ролей

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

Добавил JSDoc для новых экспортов.
Указал типы для параметров и возвращаемого значения.
Привёл пример использования.

Код-ревьювер:

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

Технический писатель / Maintainer:

Настроил шаблон и структуру документации.
Проверил генерацию страниц в CI/CD.
Провёл ревью содержания на предмет понятности для конечного пользователя.

Шаблон JSDoc для быстрой вставки

Используйте этот минимальный шаблон для функций:

/**
 * Краткое описание функции.
 * Подробности по необходимости.
 * @param {Type} name - Описание параметра.
 * @param {Type} [optional] - Необязательный параметр.
 * @returns {Type} Описание возвращаемого значения.
 * @throws {ErrorType} Условия возникновения ошибки.
 * @example
 * // Пример использования
 */
function example(name, optional) {
  // ...
}

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

Документация генерируется без ошибок командой npm run run-docs.
Все публичные функции/классы имеют блок JSDoc с @param и @returns (или явным указанием void).
Примеры в @example компилируются / работают локально.
CI проверяет генерацию документации при релизе.

Набор приёмочных тестов (коротко)

Запустить jsdoc с конфигом и убедиться, что в destination появились HTML-файлы.
Проверить, что страницы содержат описание методов и примеры.
Открыть index.html в браузере и пройти основные страницы.

Краткий глоссарий

JSDoc — инструмент для генерации документации из комментариев в JS.
@param — тег для описания параметра функции.
@returns / @return — тег для описания возвращаемого значения.
@module — указывает модуль/файл как логическую единицу.
template — шаблон для оформления HTML, используемый JSDoc.

Важно: не полагайтесь только на автоматическую документацию. Комментируйте архитектурные решения и нетривиальную логику отдельно в README или Wiki.

Быстрый набор советов («cheat sheet»)

Пишите короткие описания — одна-две строки для функции, дополняйте при необходимости.
Указывайте типы — это улучшает подсказки в IDE.
Используйте примеры — лучший способ показать ожидаемое поведение.
Поддерживайте конфиг conf.js в репозитории и интегрируйте генерацию в CI.

Итог

JSDoc — эффективный инструмент для документирования JavaScript-проектов, особенно когда нужно быстро и локально генерировать HTML-документацию из кода. Он упрощает сопровождение, помогает новым участникам быстрее понимать API и уменьшает риск потери контекста. Внедряйте JSDoc вместе с процессами ревью и CI, и документация перестанет быть «делом на потом».

Сводка: