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 riconoscono i vantaggi di 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 linguaggio Go ha GoDoc per automatizzare la documentazione dal codice, così JavaScript ha JSDoc.

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. Scriverai tutti i commenti sulla documentazione all’interno dei marcatori /** e */. 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
 */

function getUser(name) {
  const User = name;
  return User;
}

I tag @param e @returns sono due delle tante parole chiave speciali supportate da JSDoc per spiegare il codice.

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

Per esempio:

 npx jsdoc src/main.js

Se hai installato JSDoc a livello globale, puoi omettere il flag npx ed eseguire:

Questo comando genererà una cartella out nella root del progetto. All’interno della cartella troverai dei file HTML che rappresentano le pagine della tua documentazione.

È possibile visualizzare la documentazione configurando un server web locale per ospitarla 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 ed esporta 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. L’opzione modello 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 l’opzione di configurazione di destinazione su una directory. L’esempio sopra specifica una cartella di documenti 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 voce di script all’interno del file package.json:

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

Ora puoi 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 metodi di addizione e sottrazione.

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);
     */
    add: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('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);
     */
    subtract: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a - b;
    }

    
};

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 tag @module per indicare che questo file è un modulo e il tag @example 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à.