Aldonante metadatumojn al via dokumentaro
Provizi bonan dokumentadon estas esenca tasko por ĉiu programisto. Ĝi ne nur helpas viajn kunulojn rapide kompreni vian rezonadon kaj eble pensoprocezon, sed ĝi ankaŭ helpas vin eniri la kodon pli rapide, se vi revenos al ĝi post kelkaj monatoj.
Mi do pensis krei (nekompletan) liston de specialaj etikedoj por uzi kun JSDoc-komentoj. Tiuj estas tiuj, kiujn mi persone uzas plej ofte kaj kiuj pruvis havigi veran profiton.
Baza komencanto
La sekva kodekzemplo montras simplan, bazan ekzemplon, kiu devus esti uzata por ĉiu dokumentaro. Ĝi notas la celon, parametrojn same kiel la revenspecon.
/**
* 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);
}
Ekzempla kodo en la dokumentado
Vi povas provizi veran enlinian kodon ekzemplon per la etikedo "@example" por pliklarigi certajn uzkazojn. Ĉi tiu etikedo ankaŭ povas esti uzata por rapide montri eblajn randajn kazojn en reala scenaro.
/**
* 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 de kiu modulo
Uzu la "@memberOf"-etikedon por difini kiu modulo aŭ gepatra variablo gastigas la dokumentitan kodon.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Ligo komentario
Vi povas uzi la etikedon "@see" kune kun la etikedo "@link" por provizi ĝuste formatitan URL-dokumentadon, anstataŭ glui kelkajn URL-ojn enlinie de la ĉefa dokumentaro.
/**
* @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);
}
Generictipdokumentado
Se via kodo uzas ĝeneralajn tipojn, vi povas uzi la etikedon "@template" por difini la ĝeneralan tipon. Ĉi tiu nomo tiam estas uzata en la komunaj "@param"-etikedoj kiel tipreferenco.
/**
* @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);
}
Difinante la aŭtoron de peco de kodo
En certaj kazoj, gravas ankaŭ komenti la aŭtoron. Ĉi tio povas esti simple plenumita per la "@author"-etikedo. Vi povas ne nur provizi vian nomon, sed ankaŭ retpoŝton kiel kontakta referenco.
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Malrekomendita kodo
Ne estas multe por rakonti pri la "@malrekomendita"-etikedo, ĉar ĝi faras ĝuste tion, kion vi atendus. Ĉi tiu etikedo estas ofte uzata en APIoj kaj ankaŭ povas referenci la novan kodon.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Versio
Uzu la "@version"-etikedon por dokumenti version por la donita kodo. Notu, ke ĉi tiu etikedo ne referencas la aplikaĵversion, sed vere sian propran. Pliigo de ĉi tiu versio signifas, ke ĉi tiu specifa kodo ŝanĝiĝis.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Ekde kiam la kodo estas disponebla por uzi
Vi povas uzi la etikedon "@since" por dokumenti de kiu versio-numero la sekva kodo estis aldonita al la publika API. Grave rimarki ĉi tie estas, ke la versio nun referencas la aplikaĵon. Ĉi tio kontrastas kun la "@version"-etikedo de antaŭe, kiu estas ampleksa al la specifa kodbloko kiun ĝi dokumentas.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
