Jobb dokumentáció a TS & JS-ben

Hogyan írjunk jobb dokumentumokat Javascriptben gazdag metaadatokkal

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 <[email protected]>
 */
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);
}