Metaadatok hozzáadása a dokumentációhoz
A megfelelő dokumentáció biztosítása minden fejlesztő számára elengedhetetlen feladat. Nemcsak abban segít társaidnak, hogy gyorsan megértsék az érvelésedet és esetleg a gondolkodási folyamatodat, hanem abban is, hogy gyorsabban tudj belemenni a kódba, ha pár hónap múlva visszatérsz hozzá.
Ezért arra gondoltam, hogy létrehozok egy (hiányos) listát a speciális címkékről, amelyeket a JSDoc megjegyzésekhez használhatunk. Személy szerint ezeket használom a leggyakrabban, és amelyekről bebizonyosodott, hogy valódi előnyökkel járnak.
Alapvető indító
A következő kódpélda egy egyszerű, alapvető példát mutat be, amelyet minden dokumentációhoz használni kell. Megjegyzi a célt, a paramétereket, valamint a visszatérési típust.
/**
* 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);
}
Példakód a dokumentációban
Valódi sorközi kódpéldát biztosíthat a „@example” címkével, hogy bizonyos használati eseteket érthetőbbé tegyen. Ez a címke arra is használható, hogy gyorsan megjelenítse a lehetséges szélső eseteket egy valós forgatókönyvben.
/**
* 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);
}
Melyik modul tagja
Használja a „@memberOf” címkét annak meghatározásához, hogy melyik modul vagy szülőváltozó tárolja a dokumentált kódot.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Link annotáció
Használhatja a „@see” címkét a „@link” címkével együtt, hogy megfelelően formázott URL-dokumentációt biztosítson, ahelyett, hogy néhány URL-t beillesztene a fő dokumentációba.
/**
* @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);
}
Általános típusdokumentáció
Ha a kód általános típusokat használ, a „@template”-tag segítségével meghatározhatja az általános típusnevet. Ezt a nevet ezután a szokásos „@param” címkék használják típushivatkozásként.
/**
* @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);
}
Egy kódrészlet szerzőjének meghatározása
Bizonyos esetekben fontos a szerző megjegyzése is. Ez egyszerűen megvalósítható a „@author” címkével. Nem csak a nevét, hanem egy e-mail címét is megadhatja kapcsolatfelvételi hivatkozásként.
/**
* @author Tom Schönmann <tom@flaming.codes>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Elavult kód
Nincs sok mondanivaló a „@deprecated” címkéről, mivel pontosan azt csinálja, amit elvár. Ezt a címkét gyakran használják az API-kban, és hivatkozhat az új kódra is.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Változat
A „@version”-tag segítségével dokumentálhatja az adott kód verzióját. Vegye figyelembe, hogy ez a címke nem az alkalmazás verziójára hivatkozik, hanem valójában a sajátjára. Ennek a verziónak a növekedése azt jelenti, hogy ez a kód megváltozott.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Mióta használható a kód
A „@since” címkével dokumentálhatja, hogy melyik verziószámtól kezdve a következő kód került hozzáadásra a nyilvános API-hoz. Fontos megjegyezni, hogy a verzió immár az alkalmazási körre hivatkozik. Ez ellentétben áll a korábbi „@version” címkével, amely az általa dokumentált konkrét kódblokkra vonatkozik.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
