Kako dokumentirati kodo JavaScript z uporabo JSDoc

Ustrezna dokumentacija kode je pomemben, a pogosto spregledan vidik razvoja programske opreme. Kot razvijalec boste navajeni pisati čisto in učinkovito kodo, vendar boste morda manj izkušeni pri pisanju dobre dokumentacije.

Dobra dokumentacija je uporabna za vsakogar, ki dela z vašo kodo, ne glede na to, ali gre za druge člane vaše ekipe ali vas samih, pozneje. Lahko pojasni, zakaj ste nekaj implementirali na določen način ali kako uporabiti določeno funkcijo ali API.

Za razvijalce JavaScript je JSDoc dober način za začetek dokumentiranja kode.

Kaj je JSDoc?

Dokumentiranje kode je lahko zapleteno in dolgočasno. Vendar vse več ljudi prepoznava prednosti pristop "dokumenti kot koda".in številni jeziki imajo knjižnice, ki pomagajo avtomatizirati postopek. Za preprosto, jasno in jedrnato dokumentacijo. Tako kot pri Jezik Go ima GoDoc za avtomatizacijo dokumentacije iz kode, zato ima JavaScript JSDoc.

JSDoc ustvari dokumentacijo z interpretacijo posebnih komentarjev v vaši izvorni kodi JavaScript, obdelavo teh komentarjev in izdelavo dokumentacije po meri. Nato naredi to dokumentacijo na voljo v dostopnem formatu HTML.

To ohranja dokumentacijo znotraj kode, tako da je, ko posodobite kodo, dokumentacijo enostavno posodobiti.

Nastavitev JSDoc

Ustvarjalci JSDoc so olajšali začetek in nastavitev JSDoc v vašem projektu JavaScript.

Za lokalno namestitev JSDoc zaženite:

npm install --save-dev jsdoc

To bo knjižnico namestilo v vaš projekt kot odvisnost od razvijalcev.

Če želite uporabljati JSDoc, boste v izvorni kodi uporabili posebne sintaksne komentarje. Znotraj boste zapisali vse svoje pripombe k dokumentaciji /** in */ markerji. Znotraj teh lahko opišete definirane spremenljivke, funkcije, parametre funkcij in še veliko drugega.

Na primer:

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

The @param in @vrne oznake sta dve izmed številnih posebnih ključnih besed, ki jih JSDoc podpira za razlago vaše kode.

Če želite ustvariti dokumentacijo za to kodo, zaženite npx jsdoc sledi pot do vaše datoteke JavaScript.

Na primer:

npx jsdoc src/main.js

jsdoc path/to/file.js

Ta ukaz bo ustvaril ven mapo v korenu vašega projekta. Znotraj mape boste našli datoteke HTML, ki predstavljajo strani vaše dokumentacije.

Dokumentacijo si lahko ogledate na nastavitev lokalnega spletnega strežnika za gostovanjeali preprosto tako, da odprete datoteko out/index.html v brskalniku. Tukaj je primer, kako bo stran z dokumentacijo izgledala privzeto:

Konfiguriranje izhoda JSDoc

Ustvarite lahko konfiguracijsko datoteko, da spremenite privzeto vedenje JSDoc.

Če želite to narediti, ustvarite a conf.js in izvozite modul JavaScript znotraj te datoteke.

Na primer:

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

Znotraj konfiguracijske datoteke so različne Konfiguracija JSDoc opcije. The predlogo možnost vam omogoča uporabo predloge za prilagoditev videza dokumentacije. Skupnost JSDoc ponuja veliko predloge ki jih lahko uporabite. Paket vam omogoča tudi ustvarjanje lastnih prilagojenih predlog.

Če želite spremeniti lokacijo ustvarjene dokumentacije, nastavite cilj možnost konfiguracije v imenik. Zgornji primer določa a dokumenti mapo v korenu projekta.

Uporabite ta ukaz za zagon JSDoc s konfiguracijsko datoteko:

jsdoc -c /path/to/conf.js

Za lažji zagon tega ukaza ga dodajte kot a skripte vstop v vašo package.json mapa:

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

Zdaj lahko zaženite ukaz skripta npm znotraj terminala.

Primer dokumentacije, ustvarjene z JSDoc

Spodaj je preprosta aritmetična knjižnica z dodati in odšteti metode.

To je primer dobro dokumentirane kode JavaScript:

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

Komentarji JSDoc zagotavljajo jasen in celovit opis knjižnice in njenih metod, vključno z:

• Opis knjižnice in njen namen.
• Parametri vsake metode, vključno z njihovo vrsto in kratkim opisom.
• Vrednost in tip, ki ju vrne vsaka metoda.
• Napake, ki jih lahko povzroči vsaka metoda, in pogoji, ki jih povzročajo.
• Primer, kako uporabiti vsako metodo.

Komentarji vključujejo tudi @modul oznako, ki označuje, da je ta datoteka modul in @primer oznako za zagotovitev primera kode za vsako metodo.

Dokumentiranje kode razvijalca na pravi način

Kot lahko vidite, je JSDoc zelo uporabno orodje za začetek dokumentiranja kode JavaScript. S preprosto integracijo lahko med pisanjem kode ustvarite hitro in podrobno dokumentacijo. Prav tako lahko vzdržujete in posodabljate dokumentacijo kar v svojem delovnem prostoru.

Kljub temu, da je avtomatizacija JSDoc uporabna, se morate še vedno držati določenih smernic, da lahko ustvarite kakovostno dokumentacijo.