Надлежащая документация кода — важный, но часто упускаемый из виду аспект разработки программного обеспечения. Как разработчик, вы привыкли писать чистый и эффективный код, но у вас может быть меньше опыта в написании хорошей документации.
Хорошая документация полезна для всех, кто работает с вашим кодом, будь то другие члены вашей команды или вы сами, позднее. Он может объяснить, почему вы реализовали что-то определенным образом или как использовать определенную функцию или API.
Для разработчиков JavaScript JSDoc — хороший способ начать документировать свой код.
Оглавление
Что такое JSDoc?
Документирование кода может быть сложным и утомительным. Однако все больше людей осознают преимущества подхода «документы как код», и во многих языках есть библиотеки, которые помогают автоматизировать этот процесс. Для простой, ясной и краткой документации. Точно так же, как в языке Go есть GoDoc для автоматизации документации из кода, в JavaScript есть 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
*/function getUser(name) {
const User = name;
return User;
}
Теги @param и @returns — это два из многих специальных ключевых слов, которые JSDoc поддерживает для пояснения вашего кода.
Чтобы создать документацию для этого кода, запустите npx jsdoc, а затем укажите путь к файлу JavaScript.
Например:
npx jsdoc src/main.js
Если вы установили JSDoc глобально, вы можете опустить флаг npx и запустить:
Эта команда создаст папку out в корне вашего проекта. Внутри папки вы найдете 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 предоставляет множество шаблоны что вы можете использовать. Пакет также позволяет создавать собственные персонализированные шаблоны.
Чтобы изменить расположение созданной документации, установите в качестве параметра конфигурации назначения каталог. В приведенном выше примере указана папка документов в корне проекта.
Используйте эту команду для запуска JSDoc с файлом конфигурации:
jsdoc -c /path/to/conf.js
Чтобы упростить запуск этой команды, добавьте ее как запись сценария в файл package.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);
*/
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);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
Комментарии JSDoc предоставляют четкое и подробное описание библиотеки и ее методов, включая:
- Описание библиотеки и ее предназначение.
- Параметры каждого метода, включая их тип и краткое описание.
- Значение и тип, возвращаемые каждым методом.
- Ошибки, которые может выдать каждый метод, и условия, которые их вызывают.
- Пример использования каждого метода.
Комментарии также включают тег @module, указывающий, что этот файл является модулем, и тег @example, предоставляющий пример кода для каждого метода.
Правильное документирование кода разработчика
Как видите, JSDoc — очень полезный инструмент, позволяющий начать документировать код JavaScript. Благодаря простой интеграции вы можете создавать быструю и подробную документацию по мере написания кода. Вы также можете поддерживать и обновлять документацию прямо в своем рабочем пространстве.
Однако, какой бы полезной ни была автоматизация JSDoc, вам все равно следует придерживаться определенных правил, чтобы создавать качественную документацию.