Sådan dokumenteres JavaScript-kode ved hjælp af JSDoc

Korrekt kodedokumentation er et vigtigt, men ofte overset aspekt af softwareudvikling. Som udvikler vil du være vant til at skrive ren, effektiv kode, men du er måske mindre erfaren i at skrive god dokumentation.

God dokumentation er nyttig for alle, der arbejder med din kode, uanset om det er andre medlemmer af dit team eller dig selv på et senere tidspunkt. Det kan forklare, hvorfor du har implementeret noget på en bestemt måde, eller hvordan du bruger en bestemt funktion eller API.

For JavaScript-udviklere er JSDoc en god måde at begynde at dokumentere din kode på.

Hvad er JSDoc?

Dokumentation af kode kan være komplekst og kedeligt. Men flere mennesker anerkender fordelene ved en "docs as code" tilgang, og mange sprog har biblioteker, der hjælper med at automatisere processen. For enkel, klar og kortfattet dokumentation. Ligesom Go sprog har GoDoc at automatisere dokumentation fra kode, så JavaScript har JSDoc.

JSDoc genererer dokumentation ved at fortolke specielle kommentarer i din JavaScript-kildekode, behandle disse kommentarer og producere skræddersyet dokumentation. Det gør derefter denne dokumentation tilgængelig i et tilgængeligt HTML-format.

Dette holder dokumentationen i koden, så når du opdaterer din kode, er det nemt at opdatere dokumentationen.

Opsætning af JSDoc

Skaberne af JSDoc har gjort det nemt at komme i gang og opsætte JSDoc i dit JavaScript-projekt.

For at installere JSDoc lokalt skal du køre:

npm install --save-dev jsdoc

Dette vil installere biblioteket i dit projekt som en dev-afhængighed.

For at bruge JSDoc skal du bruge specielle syntakskommentarer i din kildekode. Du vil skrive alle dine dokumentationskommentarer indenfor /** og */ markører. Inde i disse kan du beskrive definerede variabler, funktioner, funktionsparametre og meget andet.

For eksempel:

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

Det @param og @vender tilbage tags er to af de mange specielle nøgleord, som JSDoc understøtter for at forklare din kode.

Kør for at generere dokumentationen til denne kode npx jsdoc efterfulgt af stien til din JavaScript-fil.

For eksempel:

npx jsdoc src/main.js

jsdoc path/to/file.js

Denne kommando vil generere en ud mappe i dit projektrod. Inde i mappen finder du HTML-filer, der repræsenterer siderne i din dokumentation.

Du kan se dokumentationen ved opsætning af en lokal webserver til at være vært for den, eller blot ved at åbne filen out/index.html inde i en browser. Her er et eksempel på, hvordan en dokumentationsside vil se ud som standard:

Konfiguration af JSDoc-output

Du kan oprette en konfigurationsfil for at ændre JSDocs standardadfærd.

For at gøre det skal du oprette en conf.js fil og eksporter et JavaScript-modul i denne fil.

For eksempel:

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

Inde i konfigurationsfilen er der forskellige JSDoc-konfiguration muligheder. Det skabelon mulighed lader dig bruge en skabelon til at tilpasse dokumentationens udseende. JSDocs fællesskab giver mange skabeloner som du kan bruge. Pakken giver dig også mulighed for at oprette dine egne personlige skabeloner.

For at ændre placeringen af ​​den genererede dokumentation skal du indstille bestemmelsessted indstillingsmulighed til en mappe. Eksemplet ovenfor angiver en dokumenter mappe i projektets rod.

Brug denne kommando til at køre JSDoc med en konfigurationsfil:

jsdoc -c /path/to/conf.js

For at gøre det nemmere at køre denne kommando, skal du tilføje den som en scripts indgang i din package.json fil:

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

Det kan du nu kør kommandoen npm script inde i en terminal.

Et eksempel på dokumentation genereret med JSDoc

Nedenfor er et simpelt aritmetisk bibliotek med tilføje og trække fra metoder.

Dette er et eksempel på veldokumenteret JavaScript-kode:

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

JSDoc-kommentarerne giver en klar og omfattende beskrivelse af biblioteket og dets metoder, herunder:

• En beskrivelse af biblioteket og dets formål.
• Hver metodes parametre, inklusive deres type og en kort beskrivelse.
• Værdien og typen, som hver metode returnerer.
• De fejl, som hver metode kan give, og de forhold, der forårsager det.
• Et eksempel på, hvordan man bruger hver metode.

Kommentarerne omfatter også @modul tag for at angive, at denne fil er et modul og @eksempel tag for at give et kodeeksempel for hver metode.

Dokumentation af udviklerkode på den rigtige måde

Som du kan se, er JSDoc et meget nyttigt værktøj til at få dig i gang med at dokumentere JavaScript-kode. Med dens nemme integration kan du generere hurtig og detaljeret dokumentation, mens du skriver din kode. Du kan også vedligeholde og opdatere dokumentationen direkte i dit arbejdsområde.

Men lige så nyttig som JSDocs automatisering er, bør du stadig overholde visse retningslinjer, så du kan oprette kvalitetsdokumentation.