JavaScript-code documenteren met JSDoc

Goede codedocumentatie is een belangrijk maar vaak over het hoofd gezien aspect van softwareontwikkeling. Als ontwikkelaar ben je gewend om schone, efficiënte code te schrijven, maar het kan zijn dat je minder ervaring hebt met het schrijven van goede documentatie.

Goede documentatie is nuttig voor iedereen die met uw code werkt, of het nu andere leden van uw team zijn of uzelf, op een later tijdstip. Het kan verklaren waarom je iets op een bepaalde manier hebt geïmplementeerd of hoe je een bepaalde functie of API moet gebruiken.

Voor JavaScript-ontwikkelaars is JSDoc een goede manier om te beginnen met het documenteren van uw code.

Wat is JSDoc?

Het documenteren van code kan complex en vervelend zijn. Steeds meer mensen zien echter de voordelen ervan in een ‘docs as code’-benadering, en veel talen hebben bibliotheken die het proces helpen automatiseren. Voor eenvoudige, duidelijke en beknopte documentatie. Net als de

JSDoc genereert documentatie door speciale opmerkingen in uw JavaScript-broncode te interpreteren, deze opmerkingen te verwerken en op maat gemaakte documentatie te produceren. Vervolgens wordt deze documentatie beschikbaar gesteld in een toegankelijk HTML-formaat.

Hierdoor blijft de documentatie binnen de code, dus wanneer u uw code bijwerkt, kunt u de documentatie eenvoudig bijwerken.

JSDoc instellen

De makers van JSDoc hebben het gemakkelijk gemaakt om aan de slag te gaan en JSDoc in uw JavaScript-project in te stellen.

Om JSDoc lokaal te installeren, voert u het volgende uit:

npm install --save-dev jsdoc

Hiermee wordt de bibliotheek in uw project geïnstalleerd als een ontwikkelaarsafhankelijkheid.

Om JSDoc te gebruiken, gebruikt u speciale syntaxisopmerkingen in uw broncode. Hierin schrijft u al uw documentatieopmerkingen /** En */ markeringen. Hierin kunt u gedefinieerde variabelen, functies, functieparameters en nog veel meer beschrijven.

Bijvoorbeeld:

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

De @param En @geeft terug tags zijn twee van de vele speciale trefwoorden die JSDoc ondersteunt om uw code uit te leggen.

Om de documentatie voor deze code te genereren, voert u uit npx jsdoc gevolgd door het pad naar uw JavaScript-bestand.

Bijvoorbeeld:

npx jsdoc src/main.js

jsdoc path/to/file.js

Deze opdracht genereert een uit map in de hoofdmap van uw project. In de map vindt u HTML-bestanden die de pagina's van uw documentatie vertegenwoordigen.

U kunt de documentatie bekijken via het opzetten van een lokale webserver om deze te hosten, of eenvoudigweg door het bestand out/index.html in een browser te openen. Hier is een voorbeeld van hoe een documentatiepagina er standaard uit zal zien:

De JSDoc-uitvoer configureren

U kunt een configuratiebestand maken om het standaardgedrag van JSDoc te wijzigen.

Maak hiervoor een conf.js bestand en exporteer een JavaScript-module binnen dit bestand.

Bijvoorbeeld:

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

In het configuratiebestand bevinden zich verschillende JSDoc-configuratie opties. De sjabloon Met deze optie kunt u een sjabloon gebruiken om het uiterlijk van de documentatie aan te passen. De gemeenschap van JSDoc biedt er veel Sjablonen die je kunt gebruiken. Met het pakket kunt u ook uw eigen gepersonaliseerde sjablonen maken.

Om de locatie van de gegenereerde documentatie te wijzigen, stelt u de bestemming config-optie naar een map. Het bovenstaande voorbeeld specificeert a documenten map in de hoofdmap van het project.

Gebruik deze opdracht om JSDoc uit te voeren met een configuratiebestand:

jsdoc -c /path/to/conf.js

Om het gemakkelijker te maken deze opdracht uit te voeren, voegt u deze toe als een scripts binnenkomst in uw pakket.json bestand:

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

Je kan nu voer de npm-scriptopdracht uit binnen een terminal.

Een voorbeeld van documentatie gegenereerd met JSDoc

Hieronder vindt u een eenvoudige rekenkundige bibliotheek met toevoegen En aftrekken methoden.

Dit is een voorbeeld van goed gedocumenteerde JavaScript-code:

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

De JSDoc-opmerkingen geven een duidelijke en uitgebreide beschrijving van de bibliotheek en haar methoden, waaronder:

• Een beschrijving van de bibliotheek en haar doel.
• De parameters van elke methode, inclusief hun type en een korte beschrijving.
• De waarde en het type dat elke methode retourneert.
• De fouten die elke methode kan veroorzaken en de omstandigheden die deze veroorzaken.
• Een voorbeeld van hoe u elke methode kunt gebruiken.

In de opmerkingen zijn ook de @module tag om aan te geven dat dit bestand een module is en de @voorbeeld tag om voor elke methode een codevoorbeeld te geven.

Ontwikkelaarscode op de juiste manier documenteren

Zoals u kunt zien, is JSDoc een zeer nuttig hulpmiddel om u op weg te helpen met het documenteren van JavaScript-code. Dankzij de eenvoudige integratie kunt u snel en gedetailleerde documentatie genereren terwijl u uw code schrijft. U kunt de documentatie ook rechtstreeks in uw werkruimte onderhouden en bijwerken.

Hoe nuttig de automatisering van JSDoc ook is, u moet zich toch aan bepaalde richtlijnen houden, zodat u kwaliteitsdocumentatie kunt maken.