Ako dokumentovať kód JavaScript pomocou JSDoc

Správna dokumentácia kódu je dôležitým, no často prehliadaným aspektom vývoja softvéru. Ako vývojár budete zvyknutí na písanie čistého a efektívneho kódu, no možno budete mať menej skúseností s písaním dobrej dokumentácie.

Dobrá dokumentácia je užitočná pre každého, kto pracuje s vaším kódom, či už ide o ostatných členov vášho tímu alebo vás neskôr. Môže vysvetliť, prečo ste niečo implementovali konkrétnym spôsobom alebo ako používať konkrétnu funkciu alebo API.

Pre vývojárov JavaScriptu je JSDoc dobrý spôsob, ako začať dokumentovať svoj kód.

Čo je JSDoc?

Dokumentovanie kódu môže byť zložité a únavné. Viac ľudí si však uvedomuje výhody prístup „dokumenty ako kód“.a mnoho jazykov má knižnice, ktoré pomáhajú automatizovať proces. Pre jednoduchú, jasnú a stručnú dokumentáciu. Rovnako ako Jazyk Go má GoDoc na automatizáciu dokumentácie z kódu, takže JavaScript má JSDoc.

JSDoc generuje dokumentáciu interpretáciou špeciálnych komentárov vo vašom zdrojovom kóde JavaScriptu, spracovaním týchto komentárov a vytváraním dokumentácie na mieru. Potom túto dokumentáciu sprístupní v dostupnom formáte HTML.

Toto uchováva dokumentáciu v kóde, takže keď aktualizujete svoj kód, je ľahké aktualizovať dokumentáciu.

Nastavenie JSDoc

Tvorcovia JSDoc uľahčili začiatok a nastavenie JSDoc vo vašom projekte JavaScript.

Ak chcete nainštalovať JSDoc lokálne, spustite:

npm install --save-dev jsdoc

Týmto sa knižnica nainštaluje do vášho projektu ako závislosť pre vývojárov.

Ak chcete použiť JSDoc, vo svojom zdrojovom kóde použijete špeciálne komentáre k syntaxi. Do nej napíšete všetky svoje pripomienky k dokumentácii /** a */ značky. V nich môžete popísať definované premenné, funkcie, parametre funkcií a mnoho iného.

Napríklad:

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

The @param a @návraty tagy sú dve z mnohých špeciálnych kľúčových slov, ktoré JSDoc podporuje na vysvetlenie vášho kódu.

Ak chcete vygenerovať dokumentáciu pre tento kód, spustite npx jsdoc nasledovaná cestou k vášmu súboru JavaScript.

Napríklad:

npx jsdoc src/main.js

jsdoc path/to/file.js

Tento príkaz vygeneruje von priečinok v koreňovom adresári vášho projektu. V priečinku nájdete súbory HTML predstavujúce stránky vašej dokumentácie.

Dokumentáciu si môžete pozrieť cez nastavenie lokálneho webového servera na jeho hosťovaniealebo jednoducho otvorením súboru out/index.html v prehliadači. Tu je príklad toho, ako bude predvolene vyzerať stránka s dokumentáciou:

Konfigurácia výstupu JSDoc

Môžete vytvoriť konfiguračný súbor na zmenu predvoleného správania JSDoc.

Ak to chcete urobiť, vytvorte a conf.js a exportujte modul JavaScript do tohto súboru.

Napríklad:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

Vo vnútri konfiguračného súboru sú rôzne Konfigurácia JSDoc možnosti. The šablóna možnosť vám umožňuje použiť šablónu na prispôsobenie vzhľadu dokumentácie. Komunita JSDoc poskytuje veľa šablóny ktoré môžete použiť. Balík vám tiež umožňuje vytvárať si vlastné personalizované šablóny.

Ak chcete zmeniť umiestnenie vygenerovanej dokumentácie, nastavte destinácia config do adresára. Vyššie uvedený príklad špecifikuje a dokumenty priečinok v koreňovom adresári projektu.

Tento príkaz použite na spustenie JSDoc s konfiguračným súborom:

jsdoc -c /path/to/conf.js

Aby bolo spustenie tohto príkazu jednoduchšie, pridajte ho ako a skripty vstup do vášho package.json súbor:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

Teraz môžeš spustite príkaz skriptu npm vnútri terminálu.

Príklad dokumentácie vygenerovanej pomocou JSDoc

Nižšie je uvedená jednoduchá aritmetická knižnica s pridať a odčítať metódy.

Toto je príklad dobre zdokumentovaného kódu 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 ...
};

Komentáre JSDoc poskytujú jasný a komplexný popis knižnice a jej metód vrátane:

• Popis knižnice a jej účelu.
• Parametre každej metódy vrátane ich typu a stručného popisu.
• Hodnota a typ, ktoré vráti každá metóda.
• Chyby, ktoré môže spôsobiť každá metóda, a podmienky, ktoré to spôsobujú.
• Príklad použitia každej metódy.

Súčasťou komentárov je aj @modul tag na označenie, že tento súbor je modul a @príklad tag na poskytnutie príkladu kódu pre každú metódu.

Dokumentácia vývojárskeho kódu správnym spôsobom

Ako vidíte, JSDoc je veľmi užitočný nástroj, ktorý vám pomôže začať dokumentovať kód JavaScript. Vďaka jednoduchej integrácii môžete pri písaní kódu vytvárať rýchlu a podrobnú dokumentáciu. Dokumentáciu môžete tiež udržiavať a aktualizovať priamo vo svojom pracovnom priestore.

Aj keď je automatizácia JSDoc užitočná, mali by ste stále dodržiavať určité pokyny, aby ste mohli vytvárať kvalitnú dokumentáciu.