A JSDoc a JavaScript-kód dokumentációs formátuma. Lehetővé teszi a fejlesztők számára, hogy strukturált megjegyzéseket adjanak a kódjukhoz, hogy leírják a függvények, változók és osztályok célját, funkcionalitását és használatát. Használhatja Typescript-fájlokban is.

Hogyan működik?

A JSDoc úgy működik, hogy speciálisan formázott megjegyzéseket használ a kódban, amelyek további információkat nyújtanak a kódelemekről. Ezek a megjegyzések /** karakterrel kezdődnek, és a kód különböző aspektusait leíró címkék követik őket.

/**
 * Multiplies two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The product of the two numbers.
 */
function multiplyNumbers(a, b) {
  return a * b;
}

A függvény 2 paramétert vesz fel, és ezek js doc formátumban vannak definiálva, és eredményt ad vissza, és a típusuk is szerepel.

A funkció magyarázatán kívül más területeken is használható

/**
 * Represents a human being.
 * @class
 */
class Human {
  /**
   * Creates a new instance of the Human class.
   * @constructor
   * @param {number} age - The age of the human.
   * @param {number} height - The height of the human in centimeters.
   * @param {number} weight - The weight of the human in kilograms.
   */
  constructor(age, height, weight) {
    this.age = age;
    this.height = height;
    this.weight = weight;
  }
}

A fenti JSDoc megjegyzésekben:

  • A @class címkével jelzi, hogy a Human egy osztály.
  • A @constructor tag az osztályon belüli konstruktor függvény leírására szolgál.
  • Minden paraméter (age, height és weight) a @param címkével van dokumentálva, megadva a paraméter nevét és típusát.

JSDoc megjegyzések használatakor támogatott konstrukciók

A JSDoc számos címkét és mintát támogat a kód dokumentálásához. Íme egy rövid magyarázat a legnépszerűbbek közül:

Típusok: Az olyan címkék, mint a @type, lehetővé teszik egy változó vagy függvény visszatérési értékének megadását, segítik a típuskövetkeztetést, és típusinformációkat biztosítanak dokumentációs célokra.

Paraméterek: Az olyan címkék, mint a @param, @arg vagy @argument dokumentumfunkció-paraméterek, megadva a nevüket, típusukat és leírásukat, hogy tisztázzák céljukat és felhasználásukat.

Visszatérési érték: Az olyan címkék, mint a @returns vagy @return, dokumentálják egy függvény visszatérési értékét, információt adva a függvény típusáról és a kapcsolódó részletekről.

Typedef: A @typedef címke egyéni típusokat vagy álneveket határoz meg összetett adatstruktúrákhoz, javítva a kód olvashatóságát és a dokumentációt.

Visszahívás: A @callback címke a visszahívási függvényeket, azok paramétereit és visszatérési típusait dokumentálja, hasznos az aszinkron programozási környezetben.

Sablon: A @template címke általános típusparamétereket határoz meg az osztályokhoz, függvényekhez vagy metódusokhoz, lehetővé téve a kód újrafelhasználhatóságát és rugalmasságát.

Osztályok: Olyan címkék, mint a @class vagy @constructor dokumentumosztályok, konstruktorok és a hozzájuk tartozó információk, beleértve az öröklődést és a megvalósított interfészeket.

Tulajdonságmódosítók: Az olyan címkék, mint a @public, @private, @protected és @readonly határozzák meg az osztálytulajdonságok hozzáférés-módosítóit és csak olvasható állapotát.

Felülbírálás és öröklődés: Az olyan címkék, mint a @override, @extends (vagy @augments) és @implements olyan osztálymetódusokat vagy -tulajdonságokat, amelyek felülbírálják vagy kiterjesztik az alaposztályokat vagy interfészeket valósítanak meg.

Ez: A @this címke a this kontextusát vagy értékét dokumentálja egy függvényen vagy metóduson belül.

Dokumentációs címkék: Az olyan címkék, mint a @deprecated, @see és @link, további dokumentációval kapcsolatos információkat nyújtanak, például az elavulási figyelmeztetéseket, a kapcsolódó dokumentációra való kereszthivatkozásokat vagy külső hivatkozásokat.

Egyéb: További címkék, mint például a @enum a felsoroláshoz és a @author a szerzők megadásához, szükség szerint használhatók.

Előfordulhat, hogy egyes címkék már nem támogatottak, ezért használat előtt érdemes ellenőrizni a dokumentációját.

Következtetés

A JSDoc egy hatékony dokumentációs formátum a JavaScript és a TypeScript számára. Segítségével strukturált megjegyzéseket adhat hozzá típusok, paraméterek, tulajdonságok stb. címkéihez. Átfogó API-dokumentációt generál, javítja a kód megértését, és népszerűsíti a legjobb gyakorlatokat. Javítja az együttműködést és az olvashatóságot a JavaScript és TypeScript fejlesztésben. A JSDoc projektbe való beépítése különösen a csapatprojektekben és a régi kóddal való foglalkozás során lehetővé teszi annak számos előnyét.

@elavult
@lásd
@link
Egyéb
@enum
@author
Egyéb támogatott minták
Nem támogatott minták
Nem támogatott címkék