Hur man dokumenterar JavaScript-kod med JSDoc

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

Bra dokumentation är användbar för alla som arbetar med din kod, oavsett om det är andra medlemmar i ditt team eller du själv vid ett senare tillfälle. Det kan förklara varför du har implementerat något på ett visst sätt eller hur du använder en viss funktion eller API.

För JavaScript-utvecklare är JSDoc ett bra sätt att börja dokumentera din kod.

Vad är JSDoc?

Att dokumentera kod kan vara komplext och tråkigt. Men fler människor inser fördelarna med en "docs as code"-metod, och många språk har bibliotek som hjälper till att automatisera processen. För enkel, tydlig och koncis dokumentation. Precis som Go language har GoDoc för att automatisera dokumentation från kod, så JavaScript har JSDoc.

JSDoc genererar dokumentation genom att tolka speciella kommentarer i din JavaScript-källkod, bearbeta dessa kommentarer och producera skräddarsydd dokumentation. Den gör sedan denna dokumentation tillgänglig i ett tillgängligt HTML-format.

Detta håller dokumentationen inom koden, så när du uppdaterar din kod är det enkelt att uppdatera dokumentationen.

Konfigurera JSDoc

Skaparna av JSDoc har gjort det enkelt att komma igång och ställa in JSDoc i ditt JavaScript-projekt.

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

npm install --save-dev jsdoc

Detta kommer att installera biblioteket i ditt projekt som ett dev-beroende.

För att använda JSDoc kommer du att använda speciella syntaxkommentarer i din källkod. Du kommer att skriva alla dina dokumentationskommentarer inom /** och */ markörer. Inuti dessa kan du beskriva definierade variabler, funktioner, funktionsparametrar och mycket annat.

Till exempel:

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

De @param och @återvänder taggar är två av de många speciella nyckelord som JSDoc stöder för att förklara din kod.

För att skapa dokumentationen för den här koden, kör npx jsdoc följt av sökvägen till din JavaScript-fil.

Till exempel:

npx jsdoc src/main.js

jsdoc path/to/file.js

Detta kommando kommer att generera en ut mapp i din projektrot. Inuti mappen hittar du HTML-filer som representerar sidorna i din dokumentation.

Du kan se dokumentationen av ställa in en lokal webbserver för att vara värd för den, eller helt enkelt genom att öppna filen out/index.html i en webbläsare. Här är ett exempel på hur en dokumentationssida kommer att se ut som standard:

Konfigurera JSDoc-utgången

Du kan skapa en konfigurationsfil för att ändra JSDocs standardbeteende.

För att göra det, skapa en conf.js fil och exportera en JavaScript-modul i den här filen.

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

Inuti konfigurationsfilen finns olika JSDoc-konfiguration alternativ. De mall alternativet låter dig använda en mall för att anpassa dokumentationens utseende. JSDocs community ger många mallar som du kan använda. Paketet låter dig också skapa dina egna personliga mallar.

För att ändra platsen för den genererade dokumentationen, ställ in destination config-alternativet till en katalog. Exemplet ovan specificerar en docs mapp i projektets rot.

Använd det här kommandot för att köra JSDoc med en konfigurationsfil:

jsdoc -c /path/to/conf.js

För att göra det enklare att köra det här kommandot, lägg till det som en manus ingång i din package.json fil:

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

Du kan nu kör kommandot npm script inuti en terminal.

Ett exempel på dokumentation genererad med JSDoc

Nedan finns ett enkelt aritmetiskt bibliotek med Lägg till och subtrahera metoder.

Det här är ett exempel på väldokumenterad JavaScript-kod:

/**
 * 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-kommentarerna ger en tydlig och heltäckande beskrivning av biblioteket och dess metoder, inklusive:

• En beskrivning av biblioteket och dess syfte.
• Varje metods parametrar, inklusive deras typ och en kort beskrivning.
• Värdet och typen som varje metod returnerar.
• De fel som varje metod kan orsaka och de förhållanden som orsakar det.
• Ett exempel på hur man använder varje metod.

Kommentarerna inkluderar också @modul taggen för att indikera att den här filen är en modul och @exempel taggen för att ge ett kodexempel för varje metod.

Dokumentera utvecklarkoden på rätt sätt

Som du kan se är JSDoc ett mycket användbart verktyg för att komma igång med att dokumentera JavaScript-kod. Med sin enkla integration kan du generera snabb och detaljerad dokumentation när du skriver din kod. Du kan också underhålla och uppdatera dokumentationen direkt i din arbetsyta.

Men lika användbar som JSDocs automatisering är, bör du fortfarande följa vissa riktlinjer så att du kan skapa kvalitetsdokumentation.