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.
Innehållsförteckning
Vad är JSDoc?
Att dokumentera kod kan vara komplext och tråkigt. Men fler människor inser fördelarna med en ”dokument som kod”-metoden, och många språk har bibliotek som hjälper till att automatisera processen. För enkel, tydlig och koncis dokumentation. Precis som Go-språket har GoDoc för att automatisera dokumentation från kod, så har JavaScript 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
*/function getUser(name) {
const User = name;
return User;
}
Taggarna @param och @returns är två av de många speciella nyckelord som JSDoc stöder för att förklara din kod.
För att generera 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
Om du installerade JSDoc globalt kan du utelämna npx-flaggan och köra:
Detta kommando genererar en ut-mapp i ditt projektrot. Inuti mappen hittar du HTML-filer som representerar sidorna i din dokumentation.
Du kan se dokumentationen genom att ställa in en lokal webbserver som 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. Mallalternativet 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 destinationskonfigurationsalternativet till en katalog. Exemplet ovan anger 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 skriptpost i filen package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Du kan nu köra kommandot npm script inuti en terminal.
Ett exempel på dokumentation genererad med JSDoc
Nedan finns ett enkelt aritmetiskt bibliotek med addera 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);
*/
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);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
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 även @module-taggen för att indikera att den här filen är en modul och @example-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.