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 aHuman
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
ésweight
) 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