Come documentare il codice JavaScript utilizzando JSDoc

La corretta documentazione del codice è un aspetto importante ma spesso trascurato dello sviluppo del software. Come sviluppatore, sarai abituato a scrivere codice pulito ed efficiente, ma potresti avere meno esperienza nello scrivere una buona documentazione.

Una buona documentazione è utile per chiunque lavori con il tuo codice, che si tratti di altri membri del tuo team o di te stesso in un secondo momento. Può spiegare perché hai implementato qualcosa in un modo particolare o come utilizzare una particolare funzione o API.

Per gli sviluppatori JavaScript, JSDoc è un buon modo per iniziare a documentare il tuo codice.

Cos'è JSDoc?

Documentare il codice può essere complesso e noioso. Tuttavia, sempre più persone ne riconoscono i vantaggi un approccio “documenti come codice”.e molte lingue dispongono di librerie che aiutano ad automatizzare il processo. Per una documentazione semplice, chiara e concisa. Proprio come il

JSDoc genera documentazione interpretando commenti speciali nel codice sorgente JavaScript, elaborando questi commenti e producendo documentazione su misura. Rende quindi disponibile questa documentazione in un formato HTML accessibile.

Ciò mantiene la documentazione all'interno del codice, quindi quando aggiorni il codice, è facile aggiornare la documentazione.

Configurazione di JSDoc

I creatori di JSDoc hanno reso semplice iniziare e configurare JSDoc nel tuo progetto JavaScript.

Per installare JSDoc localmente, eseguire:

npm install --save-dev jsdoc

Ciò installerà la libreria nel tuo progetto come dipendenza dev.

Per utilizzare JSDoc, utilizzerai speciali commenti di sintassi all'interno del tuo codice sorgente. All'interno scriverai tutti i commenti sulla documentazione /** E */ marcatori. All'interno di questi puoi descrivere variabili definite, funzioni, parametri di funzione e molto altro.

Per esempio:

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

IL @param E @ritorna i tag sono due delle tante parole chiave speciali supportate da JSDoc per spiegare il codice.

Per generare la documentazione per questo codice, esegui npxjsdoc seguito dal percorso del file JavaScript.

Per esempio:

npx jsdoc src/main.js

jsdoc path/to/file.js

Questo comando genererà un file fuori cartella nella root del progetto. All'interno della cartella troverai dei file HTML che rappresentano le pagine della tua documentazione.

È possibile visualizzare la documentazione tramite configurazione di un server web locale per ospitarlo, o semplicemente aprendo il file out/index.html all'interno di un browser. Ecco un esempio di come apparirà una pagina di documentazione per impostazione predefinita:

Configurazione dell'output JSDoc

Puoi creare un file di configurazione per modificare il comportamento predefinito di JSDoc.

Per fare ciò, crea un file conf.js file ed esportare un modulo JavaScript all'interno di questo file.

Per esempio:

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

All'interno del file di configurazione sono presenti vari Configurazione JSDoc opzioni. IL modello l'opzione ti consente di utilizzare un modello per personalizzare l'aspetto della documentazione. La comunità di JSDoc ne fornisce molti modelli che puoi usare. Il pacchetto ti consente anche di creare i tuoi modelli personalizzati.

Per modificare la posizione della documentazione generata, impostare il file destinazione opzione di configurazione in una directory. L'esempio sopra specifica a documenti cartella nella radice del progetto.

Utilizza questo comando per eseguire JSDoc con un file di configurazione:

jsdoc -c /path/to/conf.js

Per semplificare l'esecuzione di questo comando, aggiungilo come a script entrata dentro il tuo pacchetto.json file:

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

Tu puoi ora eseguire il comando script npm all'interno di un terminale.

Un esempio di documentazione generata con JSDoc

Di seguito è riportata una semplice libreria aritmetica con aggiungere E sottrarre metodi.

Questo è un esempio di codice JavaScript ben documentato:

/**
 * 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 ...
};

I commenti JSDoc forniscono una descrizione chiara ed esauriente della libreria e dei suoi metodi, tra cui:

• Una descrizione della biblioteca e del suo scopo.
• I parametri di ciascun metodo, incluso il tipo e una breve descrizione.
• Il valore e il tipo restituiti da ciascun metodo.
• Gli errori che ciascun metodo può generare e le condizioni che lo causano.
• Un esempio di come utilizzare ciascun metodo.

I commenti includono anche il @modulo tag per indicare che questo file è un modulo e il file @esempio tag per fornire un esempio di codice per ciascun metodo.

Documentare il codice dello sviluppatore nel modo giusto

Come puoi vedere, JSDoc è uno strumento molto utile per iniziare a documentare il codice JavaScript. Grazie alla sua facile integrazione, puoi generare una documentazione rapida e dettagliata mentre scrivi il codice. Puoi anche mantenere e aggiornare la documentazione direttamente nel tuo spazio di lavoro.

Tuttavia, per quanto utile sia l’automazione di JSDoc, dovresti comunque aderire a determinate linee guida in modo da poter creare documentazione di qualità.