Voeg metadata by jou dokumentasie
Die verskaffing van goeie dokumentasie is 'n noodsaaklike taak vir elke ontwikkelaar. Dit help nie net jou maats om vinnig jou redenasie en dalk denkproses te verstaan nie, maar dit help jou ook om vinniger by die kode in te kom ingeval jy na 'n paar maande daarna terugkeer.
Ek het dus gedink om 'n (onvolledige) lys van spesiale etikette te skep om saam met JSDoc-comments te gebruik. Dit is dié wat ek persoonlik die meeste gebruik en wat bewys het dat dit 'n werklike voordeel bied.
'n Basiese voorgereg
Die volgende kodevoorbeeld toon 'n eenvoudige, basiese voorbeeld wat vir elke dokumentasie gebruik moet word. Dit annoteer die doel, parameters sowel as die tipe terugkeer.
/**
* 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);
}
Voorbeeldkode in die dokumentasie
U kan 'n regte inlyn-kodevoorbeeld met die "@example"-tag verskaf om sekere gebruiksgevalle duideliker te maak. Hierdie merker kan ook gebruik word om vinnig moontlike randgevalle in 'n werklike scenario te wys.
/**
* 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);
}
Lid van watter module
Gebruik die "@memberOf"-merker om te definieer watter module of ouerveranderlike die gedokumenteerde kode huisves.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Skakelaantekening
Jy kan die "@see"-tag saam met die "@link"-tag gebruik om 'n korrek geformateerde URL-dokumentasie te verskaf, in plaas daarvan om sommige URL's inlyn van die hoofdokumentasie te plak.
/**
* @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);
}
Generiese tipe dokumentasie
As jou kode generiese tipes gebruik, kan jy die "@template"-tag gebruik om die generiese tipe naam te definieer. Hierdie naam word dan gebruik in die algemene "@param"-merkers as tipe verwysing.
/**
* @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);
}
Definieer die skrywer van 'n stuk kode
In sekere gevalle is dit belangrik om die skrywer ook te annoteer. Dit kan eenvoudig bereik word met die "@author"-tag. Jy kan nie net jou naam verskaf nie, maar ook 'n e-pos as kontakverwysing.
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Verouderde kode
Daar is nie veel om te vertel oor die "@deprecated"-tag nie, want dit doen presies wat jy sou verwag. Hierdie merker word algemeen in API's gebruik en kan ook na die nuwe kode verwys.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Weergawe
Gebruik die "@version"-tag om 'n weergawe vir die gegewe kode te dokumenteer. Let daarop dat hierdie merker nie na die toepassingweergawe verwys nie, maar regtig sy eie een. 'n Toename van hierdie weergawe beteken dat hierdie spesifieke kode verander het.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Sedert wanneer die kode beskikbaar is om te gebruik
Jy kan die "@since"-tag gebruik om te dokumenteer vanaf watter weergawenommer die volgende kode by die publieke API gevoeg is. Belangrik om hier op te let is dat die weergawe nou na die toepassingsomvang verwys. Dit kontrasteer met die "@version"-merker van voorheen, wat omvang is na die spesifieke kodeblok wat dit dokumenteer.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
