Hur man dokumenterar JavaScript-kod med JSDoc

Korrekt koddokumentation är en viktig men ofta förbisedd aspekt av programvaruutveckling. Som utvecklare är du van vid att skriva ren och effektiv kod, men du kanske är mindre van vid att skriva bra dokumentation.

Effektiv dokumentation är en ovärderlig resurs för alla som är involverade i samarbetet kring din kodbas, inklusive nuvarande och framtida iterationer av dig själv. Genom att klargöra designval och ge vägledning om hur man använder specifika funktioner eller API:er bidrar den till ökad förståelse och effektivitet bland användarna.

För de som är duktiga på JavaScript-programmering är JSDoc ett utmärkt sätt att inleda dokumentationsprocessen för sin kodbas.

Vad är JSDoc?

Det har blivit allt populärare att använda en “docs-as-code”-strategi, och många programmeringsspråk erbjuder särskilda bibliotek för att effektivisera denna process. Dessa verktyg gör det möjligt för utvecklare att generera omfattande men ändå kortfattad dokumentation utan ansträngning. Programmeringsspråket Go erbjuder exempelvis GoDoc för automatisk generering av dokumentation baserad på kodkommentarer, medan JavaScript förlitar sig på JSDoc för liknande ändamål inom sitt ekosystem.

Med hjälp av särskilda kommentarer i JavaScript-källkoden extraherar och bearbetar JSDoc effektivt sådana kommentarer för att generera skräddarsydd dokumentation. Dokumentationen formateras därefter till ett användarvänligt HTML-format för enkel åtkomst.

Genom att integrera dokumentationen direkt i källkoden underlättar detta tillvägagångssätt en sömlös process för uppdatering av både koden och dess motsvarande dokumentation när ändringar görs i den förstnämnda.

Konfigurera JSDoc

Konstruktörerna av JSDoc har förenklat processen för att initiera och integrera JSDoc i ett JavaScript-projekt, vilket gör det tillgängligt och användarvänligt från första början.

För att installera JSDoc lokalt, kör:

 npm install --save-dev jsdoc

Att installera biblioteket som ett utvecklingsberoende i ditt projekt innebär att det införlivas i projektets befintliga infrastruktur, så att du kan använda dess egenskaper och funktioner efter behov.

Hur man skriver JSDoc-kommentarer

För att använda JSDoc måste man införliva specifik kommentarsyntax direkt i sin källkod.Alla dokumentationsanmärkningar skall placeras inom ramen för taggarna / och */ / , vilka möjliggör en omfattande beskrivning av element som definierade variabler, funktioner, funktionsparametrar och diverse annan relevant information som kan beskrivas i detalj.

Till exempel:

 /**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */

function getUser(name) {
  const User = name;
  return User;
}

JSDoc är ett dokumentationsverktyg för JavaScript som använder olika specialiserade nyckelord, inklusive “@param” och “@returns”, för att skapa klarhet i koden. Dessa särskilda nyckelord fungerar som kommentarer för funktionsparametrar respektive returvärden, vilket gör det möjligt för utvecklare att bättre förstå hur deras kod ska användas och vilka resultat som kan förväntas från den.

För att skapa ett omfattande dokument som beskriver funktionerna i detta skript, kör kommandot “npx jsdoc” följt av den angivna sökvägen till din JavaScript-fil.

Till exempel:

 npx jsdoc src/main.js

Om du har installerat JSDoc som ett globalt paket kan du undvika att använda kommandot “npx” genom att helt enkelt exekvera:

 jsdoc path/to/file.js 

När du utför denna instruktion skapas en katalog med namnet “out” i den primära katalogen för ditt projekt. I denna katalog kommer du att hitta HTML-dokument som innehåller innehållet i din dokumentation.

För att få tillgång till dokumentationen har du två alternativ. Det första innebär att du konfigurerar en lokal webbserver för att fungera som värdplattform för dokumentationsfilerna. Alternativt kan du välja att öppna innehållet i filen out/index.html i din webbläsare för att visa dokumentationen direkt. Observera att standardutseendet för en dokumentationssida är följande:

Konfigurera JSDoc-utdata

Du har möjlighet att använda en anpassad konfigurationsfil för att modifiera standardfunktionerna i JSDoc.

För att uppnå detta mål är det nödvändigt att skapa en konfigurationsfil som kallas “conf.js”. Inom denna fil bör man exportera en JavaScript-modul som kommer att tjäna sitt avsedda syfte.

Till exempel:

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

I konfigurationsfilen finns olika JSDoc-konfigurationsalternativ . Med alternativet mall kan du använda en mall för att anpassa dokumentationens utseende. JSDocs community tillhandahåller många mallar som du kan använda. Paketet låter dig också skapa dina egna personliga mallar.

För att kunna flytta den automatiskt producerade dokumentationen måste man ange en specifik katalog som destination genom att justera konfigurationsinställningen “destination”. Som tidigare visats kommer detta mål att uppnås effektivt genom att ange en särskild “docs”-mapp som ligger inom projektets primära lagringsområde.

Kör följande direktiv för att använda JSDoc med hjälp av en konfigurationsfil:

 jsdoc -c /path/to/conf.js

För att förenkla utförandet av detta kommando, inkludera det som en “scripts” post i din “package.json” fil. Detta gör att kommandot enkelt kan köras var som helst i projektkatalogen genom att köra “npm run [script name]”.

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

Man kan nu köra kommandot npm script i en terminalmiljö, vilket gör det möjligt att köra de fördefinierade skriptkommandon som är associerade med Node Package Manager.

Ett exempel på dokumentation som genererats med JSDoc

Nedan följer ett elementärt aritmetiskt bibliotek med metoder för addition och subtraktion.

Detta exempel visar en kortfattad och välstrukturerad implementering av JavaScript, som kännetecknas av sin tydliga dokumentation som underlättar förståelse och underhåll.

 /**
 * 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') {
            throw new TypeError('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') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a - b;
    }

    // ... other methods ...
};

JSDoc-kommentarerna ger en djupgående och allomfattande beskrivning av biblioteket och dess funktioner, som omfattar:

Biblioteket fungerar som ett arkiv för olika litterära verk och ger låntagarna en omfattande samling av böcker som tillgodoser deras intellektuella strävanden. Dess främsta mål är att underlätta tillgången till information och kunskap, så att individer kan vidga sina vyer genom att läsa och lära. Biblioteket spelar också en viktig roll för att bevara kulturarvet genom att upprätthålla arkiv med historiska dokument och litterära skatter.

Varje enskild metods indatavariabler, inklusive deras datatyp och kortfattade förklaring.

Egenskaperna, betydelsen eller karaktären hos det resultat som genereras av varje funktion kan variera när det gäller värde och klassificering.

För att bättre förstå de potentiella problem som är förknippade med en viss metod är det viktigt att beakta både de typer av fel som kan uppstå med metoden och eventuella specifika villkor eller omständigheter under vilka dessa fel är mer benägna att uppstå. Genom att vara medveten om dessa faktorer kan utvecklare vidta åtgärder för att minska riskerna och se till att deras kod fungerar smidigt i en mängd olika situationer.

Kommentarerna i den medföljande koden innehåller två viktiga taggar, nämligen taggen “@module” och taggen “@example”.Den förra indikerar att filen är en modul, medan den senare ger ett illustrativt kodexempel för varje respektive metod. Dessa taggar fungerar som användbara referenser för utvecklare som söker vägledning om hur man använder dessa metoder effektivt inom sina egna projekt.

Dokumentera utvecklarkod på rätt sätt

JSDoc är ett effektivt sätt att skapa omfattande dokumentation av JavaScript-kod genom sömlös inkorporering i utvecklingsprocessen. Detta gör det möjligt att snabbt skapa både kortfattad och invecklad dokumentation samtidigt som det möjliggör kontinuerliga uppdateringar och revideringar inom projektmiljön.

Även om automatiseringen som tillhandahålls av JSDoc kan vara till stor hjälp för att generera dokumentation, är det ändå viktigt att man följer vissa riktlinjer och bästa praxis för att säkerställa skapandet av högkvalitativ dokumentation.