Правилна документација кода је важан, али често занемарен аспект развоја софтвера. Као програмер, бићете навикли да пишете чист, ефикасан код, али можда ћете бити мање искусни у писању добре документације.
Добра документација је корисна за свакога ко ради са вашим кодом, било да се ради о другим члановима вашег тима или вама, касније. Може да објасни зашто сте имплементирали нешто на одређени начин или како да користите одређену функцију или АПИ.
За ЈаваСцрипт програмере, ЈСДоц је добар начин да почну да документују свој код.
Преглед садржаја
Шта је ЈСДоц?
Документовање кода може бити сложено и заморно. Међутим, све више људи препознаје предности приступа „документи као код“, а многи језици имају библиотеке које помажу у аутоматизацији процеса. За једноставну, јасну и концизну документацију. Као што језик Го има ГоДоц за аутоматизацију документације из кода, тако и ЈаваСцрипт има ЈСДоц.
ЈСДоц генерише документацију тумачењем посебних коментара у вашем ЈаваСцрипт изворном коду, обрадом ових коментара и прављењем документације по мери. Затим ову документацију чини доступном у доступном ХТМЛ формату.
Ово чува документацију унутар кода, тако да када ажурирате свој код, лако је ажурирати документацију.
Подешавање ЈСДоц
Креатори ЈСДоц-а су олакшали почетак и подешавање ЈСДоц-а у вашем ЈаваСцрипт пројекту.
Да бисте инсталирали ЈСДоц локално, покрените:
npm install --save-dev jsdoc
Ово ће инсталирати библиотеку у ваш пројекат као зависност за програмере.
Да бисте користили ЈСДоц, користићете посебне синтаксне коментаре унутар вашег изворног кода. Написаћете све своје документационе коментаре унутар /** и */ маркера. Унутар њих можете описати дефинисане променљиве, функције, параметре функције и још много тога.
На пример:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
Ознаке @парам и @ретурнс су две од многих посебних кључних речи које ЈСДоц подржава да објасне ваш код.
Да бисте генерисали документацију за овај код, покрените нпк јсдоц праћен путањом до ваше ЈаваСцрипт датотеке.
На пример:
npx jsdoc src/main.js
Ако сте инсталирали ЈСДоц глобално, можете изоставити нпк заставицу и покренути:
Ова команда ће генерисати излазну фасциклу у корену вашег пројекта. Унутар фасцикле ћете пронаћи ХТМЛ датотеке које представљају странице ваше документације.
Можете погледати документацију тако што ћете подесити локални веб сервер да је хостује или једноставно отворите датотеку оут/индек.хтмл у претраживачу. Ево примера како ће страница са документацијом изгледати подразумевано:
Конфигурисање ЈСДоц излаза
Можете креирати конфигурациону датотеку да бисте променили подразумевано понашање ЈСДоц-а.
Да бисте то урадили, направите датотеку цонф.јс и извезите ЈаваСцрипт модул унутар ове датотеке.
На пример:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Унутар конфигурационог фајла су различити ЈСдоц конфигурација Опције. Опција шаблона вам омогућава да користите шаблон за прилагођавање изгледа документације. ЈСДоц-ова заједница пружа многе шаблони које можете користити. Пакет вам такође омогућава да креирате сопствене персонализоване шаблоне.
Да бисте променили локацију генерисане документације, поставите опцију одредишне конфигурације на директоријум. Пример изнад наводи фасциклу докумената у корену пројекта.
Користите ову команду да покренете ЈСДоц са конфигурационом датотеком:
jsdoc -c /path/to/conf.js
Да бисте олакшали покретање ове команде, додајте је као унос скрипте унутар датотеке пацкаге.јсон:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Сада можете покренути команду нпм сцрипт унутар терминала.
Пример документације генерисане помоћу ЈСДоц
Испод је једноставна аритметичка библиотека са методама сабирања и одузимања.
Ово је пример добро документованог ЈаваСцрипт кода:
* 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;
}
};
Коментари ЈСДоц пружају јасан и свеобухватан опис библиотеке и њених метода, укључујући:
- Опис библиотеке и њене намене.
- Параметри сваке методе, укључујући њихов тип и кратак опис.
- Вредност и тип које сваки метод враћа.
- Грешке које свака метода може бацити и услови који их узрокују.
- Пример како се користи сваки метод.
Коментари такође укључују ознаку @модуле која означава да је ова датотека модул и ознаку @екампле која пружа пример кода за сваки метод.
Документовање кода програмера на прави начин
Као што видите, ЈСДоц је веома користан алат за почетак документовања ЈаваСцрипт кода. Уз његову лаку интеграцију, можете да генеришете брзу и детаљну документацију док пишете свој код. Такође можете одржавати и ажурирати документацију директно у свом радном простору.
Међутим, колико год да је ЈСДоц-ова аутоматизација корисна, ипак би требало да се придржавате одређених смерница како бисте могли да креирате квалитетну документацију.