JSDOC documentatie generator¶

Het documenteren van code kan op verschillende manieren. Om inzicht te geven in de gedachtegang achter het ontwerp van je code kan je er een artikel over schrijven, al dan niet ondersteund met diagrammen en code snippets. Als je je documentatie alleen wilt gebruiken als naslagwerk, om later te gebruiken als je delen van je project wilt hergebruiken, kan je gebruik maken van automatische documentatie generatoren. Voor JavaScript bestaat er JSDOC.

Installatie¶

JSDOC is een node.js script. NodeJS is een programma dat je in staat stelt om javascript programma’s te draaien zonder dat je daar een webbrowser voor nodig hebt. NodeJS programmas worden vaak gebruikt om een webserver op te zetten, maar ook om hulpprogrammas te ontwikkelen, zoals JSDOC.

• Installeer eerst nodejs met npm. Volg deze link. Mac gebruikers kunnen nodejs met behulp van homebrew installeren. Linux gebruikers installeren het met apt.

• Installeer JSDOC met behulp van de “node package manager” (npm)

• Volg hier de installatie procedure

Gebruik¶

JSDOC scant gegeven javascript bestanden voor commentaar blokken die op een bepaalde manier zijn ingedeeld. Deze informatie, samen met de structuur van de code, wordt gebruikt om HTML pagina’s te genereren die als documentatie kunnen dienen.

graph LR
    id1((javascript files)) --> id2((JSDOC))
    id2((JSDOC)) --- id3((HTML files))    

Commentaar format¶

Class¶

Zie hier een voorbeeld van een commentaarblok bovenaan een class:

/**
* Brief description of the class here
* @extends SuperClassNaam
*/

Als je class ergens van overerft, moet je de super class naam invullen bij @extends.

Functie¶

Zie hier een voorbeeld van een commentaarblok bovenaan een class:

/** 
* Brief description of the function here.
* @summary If the description is long, write your summary here. Otherwise, feel free to remove this.
* @param {DataType} parameterNameHere - Brief description of the parameter here. Note: For other notations of data types, please refer to JSDocs: DataTypes command.
* @return {DataType} Brief description of the returning value here.
*/

Hier kan je de volgende onderdelen invullen:

JSDoc Gebruik¶

Om HTML pagina’s te genereren van je javascript bestanden moet je jsdoc in je command terminal draaien. Geef daarbij aan welke javascript bestanden moeten worden meegenomen:

jsdoc *.js ./gameobjects/*.js

In bovenstaand voorbeeld wordt er van uitgegaan dat er een “./gameobjects” folder bestaat waar .js bestanden in staan. Dit commando zal een map genereren waarin de HTML documentatie te vinden zal zijn.

Om tekst op de hoofdpagina van je documentatie te krijgen kan je een README.md file maken waarin je in markdown informatie over je gegenereerde documentatie kwijt kan. Om deze pagina mee te nemen in je jsdoc documentatie die je dit aan te geven in het commando, zoals:

jsdoc -R ./README.md *.js ./gameobjects/*.js

Liever markdown?¶

Een applicatie genaamd jsdoc-to-markdown is gebaseerd op jsdoc. Deze zal je jsdoc comments omzetten naar een markdown bestand.

VSCode¶

JavaScript DocStrings is een handige extensie voor VSCode die je kan helpen bij het plaatsen van “templates” voor JSDoc comments.

Bronnen¶

• jsdoc