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

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

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

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

Что такое JSDoc?

Документирование кода может быть сложным и утомительным. Однако все больше людей осознают преимущества подход «документы как код», и во многих языках есть библиотеки, которые помогают автоматизировать этот процесс. Для простой, ясной и краткой документации. Точно так же, как

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

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

Настройка JSDoc

Создатели JSDoc упростили начало работы и настройку JSDoc в вашем проекте JavaScript.

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

npm install --save-dev jsdoc

Это установит библиотеку в ваш проект как зависимость для разработчиков.

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

Например:

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

@парам и @returns Теги — это два из многих специальных ключевых слов, которые JSDoc поддерживает для пояснения вашего кода.

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

Например:

npx jsdoc src/main.js

jsdoc path/to/file.js

Эта команда создаст вне папка в корне вашего проекта. Внутри папки вы найдете HTML-файлы, представляющие страницы вашей документации.

Вы можете просмотреть документацию по настройка локального веб-сервера для его размещенияили просто открыв файл out/index.html в браузере. Вот пример того, как будет выглядеть страница документации по умолчанию:

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

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

Для этого создайте conf.js файл и экспортируйте модуль JavaScript внутри этого файла.

Например:

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

Внутри файла конфигурации находятся различные Конфигурация JSDoc параметры. шаблон Опция позволяет использовать шаблон для настройки внешнего вида документации. Сообщество JSDoc предоставляет множество шаблоны что вы можете использовать. Пакет также позволяет создавать собственные персонализированные шаблоны.

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

Используйте эту команду для запуска JSDoc с файлом конфигурации:

jsdoc -c /path/to/conf.js

Чтобы упростить запуск этой команды, добавьте ее как сценарии вход внутрь твоего пакет.json файл:

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

Ты можешь сейчас запустите команду сценария npm внутри терминала.

Пример документации, созданной с помощью JSDoc

Ниже представлена ​​простая арифметическая библиотека с добавлять и вычесть методы.

Это пример хорошо документированного кода 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') {
thrownewTypeError('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') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

Комментарии JSDoc предоставляют четкое и подробное описание библиотеки и ее методов, включая:

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

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

Правильное документирование кода разработчика

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

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