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 je hebt misschien minder ervaring met het schrijven van goede documentatie.

Effectieve documentatie is van onschatbare waarde voor iedereen die betrokken is bij de samenwerking met je codebase, inclusief huidige en toekomstige iteraties van jezelf. Door ontwerpkeuzes te verduidelijken en begeleiding te bieden bij het gebruik van specifieke functies of API’s, bevordert het meer begrip en efficiëntie onder gebruikers.

Voor degenen die bedreven zijn in het programmeren van JavaScript, is het gebruik van JSDoc een uitstekende manier om het documentatieproces voor hun codebase op te starten.

Wat is JSDoc?

Het aannemen van een “docs-as-code” strategie is steeds populairder geworden, met veel programmeertalen die speciale bibliotheken bieden om dit proces te stroomlijnen. Met deze tools kunnen ontwikkelaars moeiteloos uitgebreide maar beknopte documentatie genereren. Ter illustratie, de programmeertaal Go biedt GoDoc voor het automatisch genereren van documentatie gebaseerd op code annotaties, terwijl JavaScript vertrouwt op JSDoc voor soortgelijke doeleinden binnen zijn ecosysteem.

Door gebruik te maken van speciaal commentaar dat is ingebed in de JavaScript-broncode, haalt JSDoc op effectieve wijze dergelijke annotaties eruit en verwerkt deze om documentatie op maat te genereren. Deze documentatie wordt vervolgens geformatteerd in een gebruiksvriendelijke HTML-indeling voor gemakkelijke toegankelijkheid.

Door documentatie direct in de broncode te integreren, vergemakkelijkt deze aanpak een naadloos proces van het bijwerken van zowel de code als de bijbehorende documentatie wanneer er wijzigingen worden aangebracht in de code.

JSDoc opzetten

De ontwerpers van JSDoc hebben het proces voor het initiëren en integreren van JSDoc binnen een JavaScript-project vereenvoudigd, waardoor het vanaf het begin toegankelijk en gebruiksvriendelijk is.

Om JSDoc lokaal te installeren, voer uit:

 npm install --save-dev jsdoc

De bibliotheek installeren als een ontwikkelingsafhankelijkheid binnen uw project houdt in dat u het integreert in de bestaande infrastructuur van uw project, zodat u de mogelijkheden en functionaliteiten ervan kunt gebruiken wanneer dat nodig is.

Hoe JSDoc-commentaar te schrijven

Om JSDoc te gebruiken, moet men specifieke commentaarsyntax direct in de broncode opnemen.Alle documentatieopmerkingen moeten worden geplaatst met de tags / en */ / , waarmee een uitgebreide reeks elementen zoals gedefinieerde variabelen, functies, functieparameters en verschillende andere relevante informatie gedetailleerd kan worden beschreven.

Bijvoorbeeld:

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

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

JSDoc is een documentatietool voor JavaScript dat verschillende gespecialiseerde trefwoorden gebruikt, waaronder “@param” en “@returns”, om duidelijkheid te verschaffen over iemands code. Deze specifieke sleutelwoorden dienen als annotaties voor respectievelijk functieparameters en retourwaarden, zodat ontwikkelaars beter begrijpen hoe hun code moet worden gebruikt en welke resultaten ervan kunnen worden verwacht.

Om een uitgebreid document te maken waarin de functionaliteit van dit script wordt beschreven, voer je de opdracht “npx jsdoc” uit gevolgd door het opgegeven pad naar je JavaScript-bestand.

Bijvoorbeeld:

 npx jsdoc src/main.js

Als je JSDoc als een globaal pakket hebt geïnstalleerd, kun je het gebruik van de opdracht “npx” overslaan door eenvoudigweg uit te voeren:

 jsdoc path/to/file.js 

De uitvoering van deze opdracht resulteert in het maken van een map met de naam “out” in de hoofdmap van je project. In deze map zul je HTML-documenten vinden die de inhoud van je documentatie bevatten.

Om toegang te krijgen tot de documentatie heb je twee opties. De eerste houdt in dat je een lokale webserver configureert als hostingplatform voor de documentatiebestanden. Je kunt er ook voor kiezen om de inhoud van het out/index.html bestand te openen in de webbrowser van je voorkeur om de documentatie direct te bekijken. De documentatiepagina ziet er standaard als volgt uit:

De JSDoc-uitvoer configureren

U hebt de mogelijkheid om een aangepast configuratiebestand te gebruiken om de standaardfunctionaliteit van JSDoc aan te passen.

Om dit doel te bereiken, is het nodig om een configuratiebestand te maken dat “conf.js” wordt genoemd. Binnen dit bestand moet een JavaScript-module worden geëxporteerd die het beoogde doel dient.

Bijvoorbeeld:

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

Binnen het configuratiebestand zijn verschillende JSDoc configuratie opties. Met de sjabloonoptie kunt u een sjabloon gebruiken om het uiterlijk van de documentatie aan te passen. De gemeenschap van JSDoc biedt veel sjablonen die u kunt gebruiken. Met het pakket kunt u ook uw eigen persoonlijke sjablonen maken.

Om de automatisch geproduceerde documentatie te verplaatsen, moet je een specifieke map als bestemming aanwijzen door de configuratie-instelling met het label “destination” aan te passen. Zoals eerder is aangetoond, zal het specificeren van een aangewezen “docs” map binnen het primaire opslaggebied van het project dit doel effectief bereiken.

Voer de volgende opdracht uit om JSDoc te laten werken met een configuratiebestand:

 jsdoc -c /path/to/conf.js

Om het uitvoeren van deze opdracht te vereenvoudigen, neemt u het op als een “scripts” item in uw “package.json” bestand. Dit maakt het mogelijk om de opdracht gemakkelijk uit te voeren vanaf elke plek in je projectmap door “npm run [scriptnaam]” uit te voeren.

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

Het is nu mogelijk om het npm script commando uit te voeren in een terminalomgeving, waardoor de voorgedefinieerde scriptcommando’s van de Node Package Manager uitgevoerd kunnen worden.

Een voorbeeld van documentatie gegenereerd met JSDoc

Hieronder staat een elementaire rekenkundige bibliotheek met optel- en aftrekmethoden.

Dit voorbeeld demonstreert een beknopte en goed gestructureerde implementatie van JavaScript, gekenmerkt door de duidelijke documentatie die begrip en onderhoud vergemakkelijkt.

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

Het JSDoc-commentaar biedt een diepgaande en allesomvattende beschrijving van de bibliotheek en de functionaliteiten, waaronder:

De bibliotheek dient als een opslagplaats voor verschillende literaire werken en biedt klanten een uitgebreide collectie boeken die tegemoet komen aan hun intellectuele bezigheden. Het primaire doel is om de toegang tot informatie en kennis te vergemakkelijken, zodat mensen hun horizon kunnen verbreden door te lezen en te leren. De bibliotheek speelt ook een belangrijke rol in het behoud van cultureel erfgoed door archieven van historische documenten en literaire schatten te beheren.

De invoervariabelen van elke afzonderlijke methode, inclusief het gegevenstype en een beknopte uitleg.

De kenmerken, betekenis of aard van de output die door elke functie wordt gegenereerd, kan variëren in termen van waarde en classificatie.

Om de potentiële problemen van een bepaalde methode beter te begrijpen, is het belangrijk om zowel de soorten fouten te overwegen die door de methode kunnen worden veroorzaakt als de specifieke voorwaarden of omstandigheden waaronder deze fouten waarschijnlijker zullen optreden. Door zich bewust te zijn van deze factoren, kunnen ontwikkelaars stappen ondernemen om risico’s te beperken en ervoor zorgen dat hun code soepel werkt in verschillende situaties.

Het commentaar in de gegeven code bevat twee belangrijke tags, namelijk de “@module” tag en de “@voorbeeld” tag.De eerste geeft aan dat het bestand een module is, terwijl de tweede een illustratief codevoorbeeld geeft voor elke respectieve methode. Deze tags dienen als nuttige referenties voor ontwikkelaars die op zoek zijn naar richtlijnen om deze methoden effectief te gebruiken in hun eigen projecten.

Ontwikkelaarscode op de juiste manier documenteren

JSDoc dient inderdaad als een efficiënt middel voor het genereren van uitgebreide documentatie van JavaScript-code door naadloze integratie in het ontwikkelproces. Dit vergemakkelijkt het snel genereren van zowel beknopte als ingewikkelde documentatie en maakt tegelijkertijd continue updates en revisies binnen de projectomgeving mogelijk.

Hoewel de automatisering die JSDoc biedt heel nuttig kan zijn bij het genereren van documentatie, is het toch essentieel dat men zich houdt aan bepaalde richtlijnen en best practices om de creatie van documentatie van hoge kwaliteit te garanderen.