A megfelelő kóddokumentáció a szoftverfejlesztés fontos, de gyakran figyelmen kívül hagyott aspektusa. Fejlesztőként hozzászokott ahhoz, hogy tiszta, hatékony kódot írjon, de előfordulhat, hogy kevésbé jártas a jó dokumentáció írásában.
A jó dokumentáció mindenki számára hasznos, aki a kódjával dolgozik, legyen szó a csapat többi tagjáról, vagy Önről egy későbbi időpontban. Megmagyarázhatja, hogy miért implementált valamit egy adott módon, vagy hogyan kell egy adott függvényt vagy API-t használni.
A JavaScript-fejlesztők számára a JSDoc jó módszer a kód dokumentálásának megkezdésére.
Tartalomjegyzék
Mi az a JSDoc?
A kód dokumentálása bonyolult és fárasztó lehet. Azonban egyre többen ismerik fel a „dokumentumok kódként” megközelítés előnyeit, és sok nyelven vannak olyan könyvtárak, amelyek segítik a folyamat automatizálását. Az egyszerű, világos és tömör dokumentációért. Csakúgy, mint a Go nyelvben a GoDoc, amely automatizálja a dokumentációt a kódból, úgy a JavaScript is rendelkezik JSDoc-cal.
A JSDoc dokumentációt készít a JavaScript-forráskód speciális megjegyzéseinek értelmezésével, feldolgozza ezeket a megjegyzéseket, és személyre szabott dokumentációt készít. Ezután elérhetővé teszi ezt a dokumentációt hozzáférhető HTML formátumban.
Ez a dokumentációt a kódon belül tartja, így amikor frissíti a kódot, könnyen frissítheti a dokumentációt.
A JSDoc beállítása
A JSDoc készítői megkönnyítették az indulást és a JSDoc beállítását a JavaScript-projektben.
A JSDoc helyi telepítéséhez futtassa:
npm install --save-dev jsdoc
Ezzel fejlesztői függőségként telepíti a könyvtárat a projektben.
A JSDoc használatához speciális szintaktikai megjegyzéseket kell használnia a forráskódban. A dokumentációhoz tartozó összes megjegyzést a /** és */ jelölők közé kell írni. Ezeken belül definiált változókat, függvényeket, függvényparamétereket és még sok mást írhat le.
Például:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
A @param és @returns címkék két olyan speciális kulcsszó közül, amelyeket a JSDoc támogat a kód magyarázatára.
A kód dokumentációjának létrehozásához futtassa az npx jsdoc parancsot, majd írja be a JavaScript-fájl elérési útját.
Például:
npx jsdoc src/main.js
Ha globálisan telepítette a JSDoc-t, akkor elhagyhatja az npx jelzőt, és futtassa:
Ez a parancs létrehoz egy out mappát a projekt gyökérkönyvtárában. A mappában a dokumentáció oldalait képviselő HTML-fájlok találhatók.
A dokumentációt úgy tekintheti meg, ha beállít egy helyi webszervert a tárolására, vagy egyszerűen megnyitja az out/index.html fájlt egy böngészőben. Íme egy példa arra, hogyan fog kinézni egy dokumentációs oldal alapértelmezés szerint:
A JSDoc kimenet konfigurálása
Létrehozhat egy konfigurációs fájlt a JSDoc alapértelmezett viselkedésének megváltoztatásához.
Ehhez hozzon létre egy conf.js fájlt, és exportáljon egy JavaScript modult ebbe a fájlba.
Például:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
A konfigurációs fájlon belül különféle JSDoc konfiguráció lehetőségek. A sablon opció segítségével sablont használhat a dokumentáció megjelenésének testreszabásához. A JSDoc közössége számos szolgáltatást nyújt sablonokat hogy használhatod. A csomag lehetővé teszi saját, személyre szabott sablonok létrehozását is.
Az előállított dokumentáció helyének megváltoztatásához állítsa be a cél konfigurációs beállítást egy könyvtárra. A fenti példa egy docs mappát ad meg a projekt gyökérkönyvtárában.
Használja ezt a parancsot a JSDoc futtatásához konfigurációs fájllal:
jsdoc -c /path/to/conf.js
A parancs futtatásának megkönnyítése érdekében adja hozzá parancsfájl-bejegyzésként a package.json fájlba:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Most már futtathatja az npm script parancsot egy terminálon belül.
Példa a JSDoc segítségével generált dokumentációra
Az alábbiakban egy egyszerű aritmetikai könyvtár található összeadás és kivonás módszerekkel.
Ez egy példa a jól dokumentált JavaScript kódra:
* A library for performing basic arithmetic operations.
* @module arithmetic
*/
module.exports = {
* Adds two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @return {number} The sum of the two numbers.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const sum = arithmetic.add(5, 10);
* console.log(sum);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a + b;
},
* Subtracts the second number from the first number.
* @param {number} a - The number to subtract from.
* @param {number} b - The number to subtract.
* @return {number} The result of the subtraction.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const difference = arithmetic.subtract(10, 5);
* console.log(difference);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
A JSDoc megjegyzései világos és átfogó leírást adnak a könyvtárról és annak módszereiről, beleértve:
- A könyvtár leírása és rendeltetése.
- Az egyes módszerek paraméterei, beleértve a típusukat és egy rövid leírást.
- Az egyes metódusok által visszaadott érték és típus.
- Az egyes módszerek által okozott hibák és az azt okozó körülmények.
- Példa az egyes módszerek használatára.
A megjegyzések tartalmazzák a @module címkét is, amely jelzi, hogy ez a fájl egy modul, és a @example címkét, amely kódpéldát biztosít az egyes módszerekhez.
A fejlesztői kód megfelelő dokumentálása
Amint láthatja, a JSDoc egy nagyon hasznos eszköz a JavaScript-kód dokumentálásának megkezdéséhez. Könnyű integrációjával gyors és részletes dokumentációt készíthet a kód megírása közben. A dokumentációt közvetlenül a munkaterületén is karbantarthatja és frissítheti.
Bármennyire is hasznos a JSDoc automatizálása, mégis be kell tartania bizonyos irányelveket, hogy minőségi dokumentációt tudjon készíteni.