JavaScripti koodi dokumenteerimine JSDoc abil

Nõuetekohane koodidokumentatsioon on tarkvaraarenduse oluline, kuid sageli tähelepanuta jäetud aspekt. Arendajana olete harjunud kirjutama puhast ja tõhusat koodi, kuid võite olla vähem kogenud heade dokumentide kirjutamisel.

Hea dokumentatsioon on kasulik kõigile, kes teie koodiga töötavad, olgu selleks siis teised teie meeskonnaliikmed või teie ise, hiljem. See võib selgitada, miks olete midagi konkreetsel viisil rakendanud või kuidas konkreetset funktsiooni või API-d kasutada.

JavaScripti arendajatele on JSDoc hea viis koodi dokumenteerimise alustamiseks.

Mis on JSDoc?

Koodi dokumenteerimine võib olla keeruline ja tüütu. Kuid rohkem inimesi mõistab selle eeliseid lähenemine "dokumendid kui kood"., ja paljudes keeltes on teegid, mis aitavad protsessi automatiseerida. Lihtsa, selge ja ülevaatliku dokumentatsiooni jaoks. Täpselt nagu Go keeles on GoDoc et automatiseerida dokumentatsiooni koodist, nii et JavaScriptil on JSDoc.

JSDoc genereerib dokumentatsiooni, tõlgendades teie JavaScripti lähtekoodi erikommentaare, töötledes neid kommentaare ja koostades eritellimusel dokumentatsiooni. Seejärel teeb see dokumentatsiooni kättesaadavaks juurdepääsetavas HTML-vormingus.

See hoiab dokumentatsiooni koodi sees, nii et koodi värskendamisel on dokumentatsiooni lihtne värskendada.

JSDoc seadistamine

JSDoc loojad on muutnud alustamise ja JSDoc seadistamise teie JavaScripti projektis lihtsaks.

JSDoc kohalikuks installimiseks käivitage:

npm install --save-dev jsdoc

See installib raamatukogu teie projekti arendaja sõltuvusena.

JSDoc kasutamiseks kasutate lähtekoodis spetsiaalseid süntaksi kommentaare. Kirjutate sisse kõik oma dokumentide kommentaarid /** ja */ markerid. Nende sees saate kirjeldada määratletud muutujaid, funktsioone, funktsioonide parameetreid ja palju muud.

Näiteks:

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

The @param ja @returns sildid on kaks paljudest spetsiaalsetest märksõnadest, mida JSDoc teie koodi selgitamiseks toetab.

Selle koodi dokumentatsiooni loomiseks käivitage npx jsdoc millele järgneb teie JavaScripti faili tee.

Näiteks:

npx jsdoc src/main.js

jsdoc path/to/file.js

See käsk genereerib välja kausta oma projekti juures. Kausta seest leiate HTML-failid, mis esindavad teie dokumentatsiooni lehti.

Dokumentatsiooni saate vaadata aadressil selle hostimiseks kohaliku veebiserveri seadistaminevõi lihtsalt avades brauseris faili out/index.html. Siin on näide sellest, kuidas dokumentatsioonileht vaikimisi välja näeb.

JSDoc väljundi konfigureerimine

Saate luua konfiguratsioonifaili, et muuta JSDoc vaikekäitumist.

Selleks looge a conf.js faili ja eksportige sellesse faili JavaScripti moodul.

Näiteks:

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

Konfiguratsioonifaili sees on erinevaid JSDoc konfiguratsioon valikuid. The malli suvand võimaldab teil kasutada malli dokumentatsiooni välimuse kohandamiseks. JSDoci kogukond pakub palju mallid mida saate kasutada. Pakett võimaldab teil luua ka oma isikupärastatud malle.

Loodud dokumentatsiooni asukoha muutmiseks määrake sihtkoht config suvand kataloogi. Ülaltoodud näide täpsustab a dok projekti juurkaustas.

Kasutage seda käsku JSDoc käivitamiseks konfiguratsioonifailiga:

jsdoc -c /path/to/conf.js

Selle käsu käitamise hõlbustamiseks lisage see kui a skriptid sisestus teie sees package.json fail:

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

Nüüd saate käivitage npm skripti käsk terminali sees.

JSDoc abil loodud dokumentatsiooni näide

Allpool on lihtne aritmeetiline raamatukogu lisama ja lahutada meetodid.

See on näide hästi dokumenteeritud JavaScripti koodist:

/**
 * 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 kommentaarid annavad teegi ja selle meetodite selge ja põhjaliku kirjelduse, sealhulgas:

• Raamatukogu ja selle eesmärgi kirjeldus.
• Iga meetodi parameetrid, sealhulgas nende tüüp ja lühikirjeldus.
• Väärtus ja tüüp, mille iga meetod tagastab.
• Vead, mida iga meetod võib tekitada, ja tingimused, mis seda põhjustavad.
• Näide iga meetodi kasutamise kohta.

Kommentaarid hõlmavad ka @moodul silt, mis näitab, et see fail on moodul ja @näide iga meetodi jaoks koodinäide esitamiseks.

Arendaja koodi õige dokumenteerimine

Nagu näete, on JSDoc väga kasulik tööriist JavaScripti koodi dokumenteerimise alustamiseks. Tänu selle lihtsale integreerimisele saate koodi kirjutamisel luua kiire ja üksikasjaliku dokumentatsiooni. Samuti saate dokumentatsiooni hooldada ja värskendada otse oma tööruumis.

Kuid nii kasulik kui JSDoci automatiseerimine on, peaksite siiski järgima teatud juhiseid, et saaksite luua kvaliteetseid dokumente.