Aggiunta di metadati alla tua documentazione
Fornire una buona documentazione è un compito essenziale per ogni sviluppatore. Non solo aiuta i tuoi colleghi a capire rapidamente il tuo ragionamento e forse il processo di pensiero, ma ti aiuta anche a entrare nel codice più velocemente nel caso in cui torni ad esso dopo un paio di mesi.
Ho quindi pensato di creare un elenco (incompleto) di tag speciali da utilizzare con JSDoc-comments. Questi sono quelli che uso personalmente più spesso e che hanno dimostrato di fornire un reale vantaggio.
Un antipasto di base
L'esempio di codice seguente mostra un semplice esempio di base che dovrebbe essere usato per ogni documentazione. Annota lo scopo, i parametri e il tipo restituito.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Codice di esempio nella documentazione
Puoi fornire un vero esempio di codice inline con il tag "@example" per rendere più chiari determinati casi d'uso. Questo tag può essere utilizzato anche per mostrare rapidamente possibili casi limite in uno scenario reale.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Membro di quale modulo
Utilizzare il tag "@memberOf" per definire quale modulo o variabile padre ospita il codice documentato.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Annotazione di collegamento
Puoi utilizzare il tag "@see" insieme al tag "@link" per fornire una documentazione URL formattata correttamente, invece di incollare alcuni URL in linea nella documentazione principale.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Documentazione di tipo generico
Se il tuo codice utilizza tipi generici, puoi utilizzare il tag "@template" per definire il nome del tipo generico. Questo nome viene quindi utilizzato nei comuni tag "@param" come riferimento del tipo.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Definizione dell'autore di un pezzo di codice
In alcuni casi, è importante annotare anche l'autore. Questo può essere ottenuto semplicemente con il tag "@author". Non solo puoi fornire il tuo nome, ma anche un'e-mail come riferimento di contatto.
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Codice deprecato
Non c'è molto da dire sul tag "@deprecated", poiché fa esattamente quello che ti aspetteresti. Questo tag è comunemente usato nelle API e può anche fare riferimento al nuovo codice.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Versione
Usa il tag "@version" per documentare una versione per il codice specificato. Nota che questo tag non fa riferimento alla versione dell'applicazione, ma in realtà alla sua. Un incremento di questa versione significa che questo codice specifico è cambiato.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Da quando il codice è disponibile per l'uso
Puoi utilizzare il tag "@since" per documentare da quale numero di versione è stato aggiunto il codice seguente all'API pubblica. È importante notare che la versione ora fa riferimento all'ambito dell'applicazione. Ciò contrasta con il tag "@version" di prima, che ha come ambito il blocco di codice specifico che documenta.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
