Cum să documentați codul JavaScript folosind JSDoc

Documentarea corectă a codului este un aspect important, dar adesea trecut cu vederea, al dezvoltării software. În calitate de dezvoltator, veți fi obișnuit să scrieți cod curat și eficient, dar este posibil să aveți mai puțină experiență în scrierea unei documentații bune.

O documentație bună este utilă pentru oricine lucrează cu codul dvs., fie că este vorba de alți membri ai echipei sau de dvs., la o dată ulterioară. Poate explica de ce ați implementat ceva într-un anumit mod sau cum să utilizați o anumită funcție sau API.

Pentru dezvoltatorii JavaScript, JSDoc este o modalitate bună de a începe să vă documentați codul.

Ce este JSDoc?

Documentarea codului poate fi complexă și plictisitoare. Cu toate acestea, mai mulți oameni recunosc beneficiile o abordare „docs ca cod”.și multe limbi au biblioteci care ajută la automatizarea procesului. Pentru o documentare simplă, clară și concisă. La fel ca

JSDoc generează documentație interpretând comentarii speciale în codul sursă JavaScript, procesând aceste comentarii și producând documentație personalizată. Apoi face această documentație disponibilă într-un format HTML accesibil.

Acest lucru păstrează documentația în cod, astfel încât atunci când actualizați codul, este ușor să actualizați documentația.

Configurarea JSDoc

Creatorii JSDoc au făcut mai ușor să începeți și să configurați JSDoc în proiectul dvs. JavaScript.

Pentru a instala JSDoc local, rulați:

npm install --save-dev jsdoc

Aceasta va instala biblioteca în proiectul dvs. ca dependență de dezvoltare.

Pentru a utiliza JSDoc, veți folosi comentarii speciale de sintaxă în codul sursă. Veți scrie toate comentariile de documentare în interior /** și */ markere. În interiorul acestora, puteți descrie variabile definite, funcții, parametrii funcției și multe altele.

De exemplu:

/**
 * 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 @se intoarce etichetele sunt două dintre multele cuvinte cheie speciale pe care le acceptă JSDoc pentru a explica codul dvs.

Pentru a genera documentația pentru acest cod, rulați npx jsdoc urmat de calea către fișierul JavaScript.

De exemplu:

npx jsdoc src/main.js

jsdoc path/to/file.js

Această comandă va genera un afară folderul din rădăcina proiectului. În interiorul folderului, veți găsi fișiere HTML reprezentând paginile documentației dvs.

Puteți vizualiza documentația prin configurarea unui server web local pentru a-l găzdui, sau pur și simplu prin deschiderea fișierului out/index.html în interiorul unui browser. Iată un exemplu despre cum va arăta implicit o pagină de documentație:

Configurarea ieșirii JSDoc

Puteți crea un fișier de configurare pentru a schimba comportamentul implicit al JSDoc.

Pentru a face acest lucru, creați un conf.js fișier și exportați un modul JavaScript în interiorul acestui fișier.

De exemplu:

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

În interiorul fișierului de configurare sunt diverse Configurare JSDoc Opțiuni. The șablon opțiunea vă permite să utilizați un șablon pentru a personaliza aspectul documentației. Comunitatea JSDoc oferă multe șabloane pe care le poți folosi. Pachetul vă permite, de asemenea, să vă creați propriile șabloane personalizate.

Pentru a schimba locația documentației generate, setați destinaţie opțiunea de configurare într-un director. Exemplul de mai sus specifică a docs folderul din rădăcina proiectului.

Utilizați această comandă pentru a rula JSDoc cu un fișier de configurare:

jsdoc -c /path/to/conf.js

Pentru a ușura rularea acestei comenzi, adăugați-o ca a scenarii intrare în interiorul dvs pachet.json fişier:

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

Acuma poți rulați comanda script-ului npm în interiorul unui terminal.

Un exemplu de documentație generată cu JSDoc

Mai jos este o bibliotecă aritmetică simplă cu adăuga și scădea metode.

Acesta este un exemplu de cod JavaScript bine documentat:

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

Comentariile JSDoc oferă o descriere clară și cuprinzătoare a bibliotecii și a metodelor acesteia, inclusiv:

• O descriere a bibliotecii și a scopului acesteia.
• Parametrii fiecărei metode, inclusiv tipul lor și o scurtă descriere.
• Valoarea și tipul pe care le returnează fiecare metodă.
• Erorile pe care le poate arunca fiecare metodă și condițiile care le provoacă.
• Un exemplu de utilizare a fiecărei metode.

Comentariile includ și @modul etichetă pentru a indica faptul că acest fișier este un modul și @exemplu etichetă pentru a oferi un exemplu de cod pentru fiecare metodă.

Documentarea codului de dezvoltator în mod corect

După cum puteți vedea, JSDoc este un instrument foarte util pentru a începe să documentați codul JavaScript. Cu integrarea sa ușoară, puteți genera documentație rapidă și detaliată pe măsură ce scrieți codul. De asemenea, puteți întreține și actualiza documentația chiar în spațiul dvs. de lucru.

Cu toate acestea, pe cât de utilă este automatizarea lui JSDoc, ar trebui să respectați în continuare anumite linii directoare, astfel încât să puteți crea documentație de calitate.