Kako dokumentirati JavaScript kod koristeći JSDoc

Pravilna dokumentacija koda važan je, ali često zanemaren aspekt razvoja softvera. Kao programer, naviknut ćete pisati čist, učinkovit kod, ali možda ćete imati manje iskustva u pisanju dobre dokumentacije.

Dobra dokumentacija korisna je svima koji rade s vašim kodom, bilo da se radi o drugim članovima vašeg tima ili vama samima, kasnije. Može objasniti zašto ste nešto implementirali na određeni način ili kako koristiti određenu funkciju ili API.

Za JavaScript programere, JSDoc je dobar način za početak dokumentiranja vašeg koda.

Što je JSDoc?

Dokumentiranje koda može biti složeno i zamorno. Međutim, sve više ljudi prepoznaje prednosti pristup "dokumenti kao kod"., a mnogi jezici imaju biblioteke koje pomažu automatizirati proces. Za jednostavnu, jasnu i konciznu dokumentaciju. Baš poput Go jezik ima GoDoc za automatizaciju dokumentacije iz koda, tako da JavaScript ima JSDoc.

JSDoc generira dokumentaciju tumačenjem posebnih komentara u vašem JavaScript izvornom kodu, obradom tih komentara i izradom prilagođene dokumentacije. Zatim ovu dokumentaciju čini dostupnom u pristupačnom HTML formatu.

Ovo čuva dokumentaciju unutar koda, tako da kada ažurirate svoj kod, lako je ažurirati dokumentaciju.

Postavljanje JSDoc

Kreatori JSDoc-a olakšali su početak i postavljanje JSDoc-a u vašem JavaScript projektu.

Da biste instalirali JSDoc lokalno, pokrenite:

npm install --save-dev jsdoc

Ovo će instalirati biblioteku u vaš projekt kao ovisnost o programerima.

Da biste koristili JSDoc, upotrijebit ćete posebne komentare sintakse unutar svog izvornog koda. Unutar ćete napisati sve svoje komentare na dokumentaciju /** i */ oznake. Unutar njih možete opisati definirane varijable, funkcije, parametre funkcije i još mnogo toga.

Na primjer:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

The @param i @vraća oznake su dvije od mnogih posebnih ključnih riječi koje JSDoc podržava za objašnjenje vašeg koda.

Da biste generirali dokumentaciju za ovaj kod, pokrenite npx jsdoc nakon čega slijedi put do vaše JavaScript datoteke.

Na primjer:

npx jsdoc src/main.js

jsdoc path/to/file.js

Ova naredba će generirati van mapu u korijenu vašeg projekta. Unutar mape pronaći ćete HTML datoteke koje predstavljaju stranice vaše dokumentacije.

Dokumentaciju možete pogledati na postavljanje lokalnog web poslužitelja koji će ga ugostiti, ili jednostavno otvaranjem datoteke out/index.html unutar preglednika. Evo primjera kako će stranica dokumentacije izgledati prema zadanim postavkama:

Konfiguriranje JSDoc izlaza

Možete izraditi konfiguracijsku datoteku za promjenu zadanog ponašanja JSDoc-a.

Da biste to učinili, stvorite a conf.js datoteku i izvezite JavaScript modul unutar ove datoteke.

Na primjer:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

Unutar konfiguracijske datoteke nalaze se razni JSDoc konfiguracija opcije. The šablona opcija vam omogućuje korištenje predloška za prilagodbu izgleda dokumentacije. JSDoc-ova zajednica pruža mnoge šablone koje možete koristiti. Paket vam također omogućuje stvaranje vlastitih personaliziranih predložaka.

Da biste promijenili mjesto generirane dokumentacije, postavite odredište opciju konfiguracije u direktorij. Gornji primjer specificira a dokumenti mapu u korijenu projekta.

Koristite ovu naredbu za pokretanje JSDoc s konfiguracijskom datotekom:

jsdoc -c /path/to/conf.js

Da biste olakšali izvođenje ove naredbe, dodajte je kao skripte ulaz unutar vašeg paket.json datoteka:

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

Sada možete pokrenite naredbu skripte npm unutar terminala.

Primjer dokumentacije generirane s JSDoc

Ispod je jednostavna aritmetička biblioteka s dodati i oduzeti metode.

Ovo je primjer dobro dokumentiranog JavaScript koda:

/**
 * 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 ...
};

Komentari JSDoc pružaju jasan i sveobuhvatan opis biblioteke i njezinih metoda, uključujući:

• Opis knjižnice i njezine namjene.
• Parametri svake metode, uključujući njihovu vrstu i kratak opis.
• Vrijednost i tip koje svaka metoda vraća.
• Pogreške koje svaka metoda može izazvati i uvjeti koji ih uzrokuju.
• Primjer korištenja svake metode.

Komentari također uključuju @modul oznaku koja označava da je ova datoteka modul i @primjer oznaku za pružanje primjera koda za svaku metodu.

Dokumentiranje razvojnog koda na pravi način

Kao što vidite, JSDoc je vrlo koristan alat za početak dokumentiranja JavaScript koda. Uz njegovu jednostavnu integraciju, možete generirati brzu i detaljnu dokumentaciju dok pišete svoj kod. Također možete održavati i ažurirati dokumentaciju izravno u svom radnom prostoru.

Međutim, koliko god JSDoc-ova automatizacija bila korisna, ipak biste se trebali pridržavati određenih smjernica kako biste mogli izraditi kvalitetnu dokumentaciju.