Правилната документация на кода е важен, но често пренебрегван аспект от разработката на софтуер. Като разработчик ще сте свикнали да пишете чист, ефективен код, но може да имате по-малко опит в писането на добра документация.
Добрата документация е полезна за всеки, който работи с вашия код, независимо дали това са други членове на вашия екип или вие самите, на по-късна дата. Може да обясни защо сте внедрили нещо по определен начин или как да използвате определена функция или 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 и да изпълните:
Тази команда ще генерира изходяща папка в корена на вашия проект. Вътре в папката ще намерите 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, все пак трябва да се придържате към определени насоки, за да можете да създавате качествена документация.