Hvordan dokumentere JavaScript-kode ved hjelp av JSDoc

Riktig kodedokumentasjon er et viktig, men ofte oversett aspekt ved programvareutvikling. Som utvikler vil du være vant til å skrive ren, effektiv kode, men du kan være mindre erfaren med å skrive god dokumentasjon.

God dokumentasjon er nyttig for alle som jobber med koden din, enten det er andre medlemmer av teamet ditt, eller deg selv på et senere tidspunkt. Det kan forklare hvorfor du har implementert noe på en bestemt måte eller hvordan du bruker en bestemt funksjon eller API.

For JavaScript-utviklere er JSDoc en god måte å begynne å dokumentere koden på.

Hva er JSDoc?

Å dokumentere kode kan være komplisert og kjedelig. Men flere mennesker erkjenner fordelene med en "dokumenter som kode"-tilnærming, og mange språk har biblioteker som hjelper til med å automatisere prosessen. For enkel, klar og konsis dokumentasjon. Akkurat som Go-språket har GoDoc å automatisere dokumentasjon fra kode, så JavaScript har JSDoc.

JSDoc genererer dokumentasjon ved å tolke spesielle kommentarer i JavaScript-kildekoden din, behandle disse kommentarene og produsere skreddersydd dokumentasjon. Den gjør deretter denne dokumentasjonen tilgjengelig i et tilgjengelig HTML-format.

Dette holder dokumentasjonen innenfor koden, så når du oppdaterer koden din, er det enkelt å oppdatere dokumentasjonen.

Sette opp JSDoc

Skaperne av JSDoc har gjort det enkelt å komme i gang og sette opp JSDoc i JavaScript-prosjektet ditt.

For å installere JSDoc lokalt, kjør:

npm install --save-dev jsdoc

Dette vil installere biblioteket i prosjektet ditt som en utviklingsavhengighet.

For å bruke JSDoc, vil du bruke spesielle syntakskommentarer inne i kildekoden. Du vil skrive alle dokumentasjonskommentarene dine /** og */ markører. Inne i disse kan du beskrive definerte variabler, funksjoner, funksjonsparametere og mye annet.

For eksempel:

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

De @param og @returnerer koder er to av de mange spesielle nøkkelordene som JSDoc støtter for å forklare koden din.

For å generere dokumentasjonen for denne koden, kjør npx jsdoc etterfulgt av banen til JavaScript-filen.

For eksempel:

npx jsdoc src/main.js

jsdoc path/to/file.js

Denne kommandoen vil generere en ute mappe i prosjektroten din. Inne i mappen finner du HTML-filer som representerer sidene i dokumentasjonen din.

Du kan se dokumentasjonen ved å sette opp en lokal webserver for å være vert for den, eller ganske enkelt ved å åpne out/index.html-filen i en nettleser. Her er et eksempel på hvordan en dokumentasjonsside vil se ut som standard:

Konfigurere JSDoc-utgangen

Du kan opprette en konfigurasjonsfil for å endre JSDocs standardoppførsel.

For å gjøre det, opprette en conf.js fil og eksporter en JavaScript-modul i denne filen.

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,
 },
};

Inne i konfigurasjonsfilen er det forskjellige JSDoc-konfigurasjon alternativer. De mal alternativet lar deg bruke en mal for å tilpasse dokumentasjonens utseende. JSDocs fellesskap gir mange maler som du kan bruke. Pakken lar deg også lage dine egne personlige maler.

For å endre plasseringen til den genererte dokumentasjonen, angi mål konfigurasjonsalternativet til en katalog. Eksemplet ovenfor spesifiserer en dokumenter mappe i prosjektets rot.

Bruk denne kommandoen til å kjøre JSDoc med en konfigurasjonsfil:

jsdoc -c /path/to/conf.js

For å gjøre det enklere å kjøre denne kommandoen, legg den til som en skript oppføring i din package.json fil:

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

Du kan nå kjør kommandoen npm script inne i en terminal.

Et eksempel på dokumentasjon generert med JSDoc

Nedenfor er et enkelt aritmetisk bibliotek med Legg til og trekke fra metoder.

Dette er et eksempel på godt dokumentert 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-kommentarene gir en klar og omfattende beskrivelse av biblioteket og dets metoder, inkludert:

• En beskrivelse av biblioteket og dets formål.
• Hver metodes parametere, inkludert deres type og en kort beskrivelse.
• Verdien og typen som hver metode returnerer.
• Feilene som hver metode kan gi og forholdene som forårsaker det.
• Et eksempel på hvordan du bruker hver metode.

Kommentarene inkluderer også @modul tag for å indikere at denne filen er en modul og @eksempel tag for å gi et kodeeksempel for hver metode.

Dokumentere utviklerkode på riktig måte

Som du kan se, er JSDoc et veldig nyttig verktøy for å komme i gang med å dokumentere JavaScript-kode. Med den enkle integrasjonen kan du generere rask og detaljert dokumentasjon mens du skriver koden. Du kan også vedlikeholde og oppdatere dokumentasjonen rett i arbeidsområdet ditt.

Men så nyttig som JSDocs automatisering er, bør du fortsatt følge visse retningslinjer slik at du kan lage kvalitetsdokumentasjon.