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

Правилната документация на кода е важен, но често пренебрегван аспект от разработката на софтуер. Като разработчик ще сте свикнали да пишете чист, ефективен код, но може да имате по-малко опит в писането на добра документация.

Добрата документация е полезна за всеки, който работи с вашия код, независимо дали това са други членове на вашия екип или вие самите на по-късна дата. Може да обясни защо сте внедрили нещо по определен начин или как да използвате определена функция или 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
 */
functiongetUser(name) {
const User = name;
return User;
}

The @param и @се завръща таговете са две от многото специални ключови думи, които JSDoc поддържа, за да обясни вашия код.

За да генерирате документацията за този код, стартирайте npx jsdoc последвано от пътя до вашия JavaScript файл.

Например:

npx jsdoc src/main.js

jsdoc path/to/file.js

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

Можете да разгледате документацията от настройване на локален уеб сървър, който да го хоства, или просто като отворите файла out/index.html в браузър. Ето пример за това как ще изглежда страницата с документация по подразбиране:

Конфигуриране на изхода на JSDoc

Можете да създадете конфигурационен файл, за да промените поведението по подразбиране на JSDoc.

За да направите това, създайте a 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 настроики. The шаблон опция ви позволява да използвате шаблон, за да персонализирате външния вид на документацията. Общността на JSDoc предоставя много шаблони които можете да използвате. Пакетът също ви позволява да създавате свои собствени персонализирани шаблони.

За да промените местоположението на генерираната документация, задайте дестинация опция за конфигурация към директория. Примерът по-горе уточнява a документи папка в корена на проекта.

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

jsdoc -c /path/to/conf.js

За да улесните изпълнението на тази команда, добавете я като a скриптове влизане във вашия 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); // 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, все пак трябва да се придържате към определени указания, за да можете да създавате качествена документация.