Како документовати ЈаваСцрипт код користећи ЈСДоц

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

Добра документација је корисна за свакога ко ради са вашим кодом, било да се ради о другим члановима вашег тима или вама, касније. Може да објасни зашто сте имплементирали нешто на одређени начин или како да користите одређену функцију или АПИ.

За ЈаваСцрипт програмере, ЈСДоц је добар начин да почну да документују свој код.

Шта је ЈСДоц?

Документовање кода може бити сложено и заморно. Међутим, све више људи препознаје предности приступ „документи као код“., а многи језици имају библиотеке које помажу у аутоматизацији процеса. За једноставну, јасну и концизну документацију. Баш као и Го језик има ГоДоц да аутоматизује документацију из кода, тако да ЈаваСцрипт има ЈСДоц.

ЈСДоц генерише документацију тумачењем посебних коментара у вашем ЈаваСцрипт изворном коду, обрадом ових коментара и прављењем документације по мери. Затим ову документацију чини доступном у доступном ХТМЛ формату.

Ово чува документацију унутар кода, тако да када ажурирате свој код, лако је ажурирати документацију.

Подешавање ЈСДоц

Креатори ЈСДоц-а су олакшали почетак и подешавање ЈСДоц-а у вашем ЈаваСцрипт пројекту.

Да бисте локално инсталирали ЈСДоц, покрените:

npm install --save-dev jsdoc

Ово ће инсталирати библиотеку у ваш пројекат као зависност за програмере.

Да бисте користили ЈСДоц, користићете посебне синтаксне коментаре унутар вашег изворног кода. Написаћете све своје коментаре на документацију /** и */ маркери. Унутар њих можете описати дефинисане променљиве, функције, параметре функције и још много тога.

На пример:

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

Тхе @парам и @ретурнс ознаке су две од многих специјалних кључних речи које ЈСДоц подржава да објасне ваш код.

Да бисте генерисали документацију за овај код, покрените нпк јсдоц праћено путањом до ваше ЈаваСцрипт датотеке.

На пример:

npx jsdoc src/main.js

jsdoc path/to/file.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); // 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 ...
};

Коментари ЈСДоц пружају јасан и свеобухватан опис библиотеке и њених метода, укључујући:

• Опис библиотеке и њене намене.
• Параметри сваке методе, укључујући њихов тип и кратак опис.
• Вредност и тип које сваки метод враћа.
• Грешке које свака метода може бацити и услови који их узрокују.
• Пример како се користи сваки метод.

Коментари такође укључују @модуле ознаку која означава да је ова датотека модул и @екампле таг да обезбеди пример кода за сваки метод.

Документовање кода програмера на прави начин

Као што видите, ЈСДоц је веома користан алат за почетак документовања ЈаваСцрипт кода. Уз његову лаку интеграцију, можете да генеришете брзу и детаљну документацију док пишете свој код. Такође можете одржавати и ажурирати документацију директно у свом радном простору.

Међутим, колико год да је ЈСДоц-ова аутоматизација корисна, ипак би требало да се придржавате одређених смерница како бисте могли да креирате квалитетну документацију.