Importanța Documentației Codului și JSDoc
Documentarea corectă a codului reprezintă un element esențial, deși adesea neglijat, în procesul de dezvoltare software. Ca dezvoltator, ești obișnuit să creezi cod curat și eficient, dar s-ar putea să nu ai la fel de multă experiență în redactarea unei documentații de calitate.
O documentație bine realizată este extrem de valoroasă pentru oricine interacționează cu codul tău, fie că este vorba de colegii din echipă sau chiar de tine însuți, într-o etapă ulterioară. Ea poate oferi explicații despre alegerile de implementare, modul de utilizare a funcțiilor sau a API-urilor.
Pentru programatorii JavaScript, JSDoc este o metodă excelentă de a începe documentarea codului.
Ce este JSDoc?
Procesul de documentare a codului poate fi complex și laborios. Cu toate acestea, tot mai mulți programatori conștientizează avantajele abordării „documentație ca și cod”, iar multe limbaje de programare oferă biblioteci care automatizează acest proces. Pentru o documentație simplă, clară și concisă, JSDoc este echivalentul GoDoc pentru limbajul JavaScript.
JSDoc generează documentație prin interpretarea comentariilor speciale din codul sursă JavaScript. Acesta procesează aceste comentarii și creează o documentație personalizată, disponibilă într-un format HTML accesibil.
Astfel, documentația rămâne integrată în cod, ceea ce facilitează actualizarea acesteia odată cu modificările codului.
Configurarea JSDoc
Creatorii JSDoc au simplificat procesul de instalare și configurare a JSDoc în proiectul tău JavaScript.
Pentru a instala JSDoc local, execută următoarea comandă:
npm install --save-dev jsdoc
Această comandă adaugă biblioteca ca dependență de dezvoltare a proiectului tău.
Pentru a folosi JSDoc, vei utiliza comentarii cu o sintaxă specifică în codul sursă. Comentariile de documentare vor fi scrise între marcatoarele /** și */. În interiorul acestora, poți descrie variabile definite, funcții, parametrii funcțiilor și multe altele.
Exemplu:
* Obține un utilizator după nume.
* @param {string} name - Numele utilizatorului
* @returns {string} Utilizatorul
*/
function getUser(name) {
const User = name;
return User;
}
Etichetele @param și @returns sunt doar două exemple dintre numeroasele cuvinte cheie speciale pe care JSDoc le recunoaște pentru a explica codul tău.
Pentru a genera documentația din acest cod, execută comanda npx jsdoc urmată de calea către fișierul JavaScript.
Exemplu:
npx jsdoc src/main.js
Dacă ai instalat JSDoc global, poți omite npx și executa:
Această comandă va genera un folder „out” în directorul rădăcină al proiectului. În interiorul acestui folder, vei găsi fișiere HTML care reprezintă paginile documentației.
Poți vizualiza documentația fie instalând un server web local, fie deschizând fișierul out/index.html într-un browser. Iată un exemplu despre cum arată o pagină de documentație în mod implicit:
Configurarea Ieșirii JSDoc
Poți crea un fișier de configurare pentru a personaliza comportamentul implicit al JSDoc.
Pentru aceasta, creează un fișier conf.js și exportă un modul JavaScript în interiorul acestuia.
Exemplu:
module.exports = {
source: {
includePattern: ".+\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Fișierul de configurare acceptă diverse opțiuni de configurare JSDoc. Opțiunea „template” îți permite să utilizezi un șablon pentru a personaliza aspectul documentației. Comunitatea JSDoc oferă multe șabloane pe care le poți folosi. De asemenea, poți crea propriile șabloane personalizate.
Pentru a schimba locația documentației generate, setează opțiunea „destination” la un director. În exemplul de mai sus, documentația va fi generată într-un folder „docs” din rădăcina proiectului.
Pentru a executa JSDoc cu un fișier de configurare, folosește comanda:
jsdoc -c /path/to/conf.js
Pentru a facilita execuția acestei comenzi, o poți adăuga ca script în fișierul package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Acum poți rula comanda script-ului npm dintr-un terminal.
Exemplu de Documentație Generată cu JSDoc
Mai jos este un exemplu de bibliotecă aritmetică simplă, cu metode de adunare și scădere.
Acesta este un exemplu de cod JavaScript bine documentat:
* O bibliotecă pentru operații aritmetice de bază.
* @module arithmetic
*/
module.exports = {
/**
* Adună două numere.
* @param {number} a - Primul număr.
* @param {number} b - Al doilea număr.
* @return {number} Suma celor două numere.
* @throws {TypeError} Dacă oricare dintre argumente nu este un număr.
*
* @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('Ambele argumente trebuie să fie numere.');
}
return a + b;
},
/**
* Scade al doilea număr din primul număr.
* @param {number} a - Numărul din care se scade.
* @param {number} b - Numărul de scăzut.
* @return {number} Rezultatul scăderii.
* @throws {TypeError} Dacă oricare dintre argumente nu este un număr.
*
* @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('Ambele argumente trebuie să fie numere.');
}
return a - b;
}
};
Comentariile JSDoc oferă o descriere clară și completă a bibliotecii și a metodelor sale, incluzând:
- O descriere a bibliotecii și a scopului acesteia.
- Parametrii fiecărei metode, cu tipul și o scurtă descriere.
- Valoarea și tipul returnat de fiecare metodă.
- Erorile pe care le poate arunca fiecare metodă și condițiile care le provoacă.
- Un exemplu de utilizare a fiecărei metode.
Comentariile includ, de asemenea, eticheta @module pentru a indica faptul că acest fișier reprezintă un modul, precum și eticheta @example pentru a oferi un exemplu de cod pentru fiecare metodă.
Documentarea Eficientă a Codului
După cum se poate observa, JSDoc este un instrument extrem de util pentru a începe documentarea codului JavaScript. Datorită integrării sale facile, poți genera rapid documentație detaliată pe măsură ce scrii codul. De asemenea, poți menține și actualiza documentația direct în spațiul tău de lucru.
Cu toate acestea, oricât de utilă ar fi automatizarea oferită de JSDoc, este esențial să respecți anumite reguli pentru a crea o documentație de calitate.