A JavaScript kód dokumentálása a JSDoc használatával

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 lehet, 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 Önről. 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.

Mi az a JSDoc?

A kód dokumentálása bonyolult és fárasztó lehet. Azonban egyre többen ismerik fel az előnyeit a „dokumentumok kódként” megközelítés, és sok nyelvben 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

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 bele kell írnia /** és */ markerek. 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
 */
functiongetUser(name) {
const User = name;
return User;
}

A @param és @visszatér A címkék kettő a sok 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 npx jsdoc ezt követi a JavaScript-fájl elérési útja.

Például:

npx jsdoc src/main.js

jsdoc path/to/file.js

Ez a parancs generál egy ki mappát a projekt gyökérjében. A mappában a dokumentáció oldalait képviselő HTML-fájlok találhatók.

A dokumentációt megtekintheti a helyi webszerver beállítása a tárolására, vagy egyszerűen az out/index.html fájl megnyitásával a 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 a 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 sok mindent kínál sablonokat hogy használhatod. A csomag lehetővé teszi saját, személyre szabott sablonok létrehozását is.

A generált dokumentáció helyének módosításához állítsa be a rendeltetési hely config opciót egy könyvtárba. A fenti példa megadja a dok mappát 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á a forgatókönyvek belépés az Ön belsejébe package.json fájl:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

Most tudsz futtassa az npm script parancsot 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ó add hozzá és kivonni mód.

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); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('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); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

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 a 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 között szerepel még a @modul címke jelzi, hogy ez a fájl egy modul, és a @példa címkét, hogy minden metódushoz kódpéldát adjon.

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.