JSDoc: de documentatie-spierballen van JavaScript

Er zijn verschillende manieren om documentatie goed bij te houden, maar mijn persoonlijke favoriet is JSDoc. JSDoc is een krachtige open-source tool voor JavaScript-ontwikkelaars die gedetailleerde documentatie voor hun code willen genereren. Met JSDoc kan je automatisch HTML-documentatie genereren vanuit speciaal geformatteerde commentaarblokken in de broncode. Dit helpt ontwikkelaars om consistente en gemakkelijk te raadplegen documentatie te creëren zonder extra inspanning. Het bespaart tijd, energie en dus ook geld. Een win-win-win situatie!

JSDoc is al een tijdje beschikbaar, maar met de release van versie 4.0.X en een indrukwekkend aantal downloads op npm (2 tot 3 miljoen), blijft het een veelgebruikte tool onder ontwikkelaars.

Wat kan je met JSDoc doen?

JSDoc wordt gebruikt voor een breed scala aan toepassingen, waaronder:

• Code-onderhoud: Door duidelijke documentatie direct in de broncode op te nemen, kunnen ontwikkelaars en teams makkelijker de werking en bedoeling van code begrijpen en onderhouden.
• API-documentatie: JSDoc is ideaal voor het documenteren van API’s. Het genereert automatisch gestructureerde en leesbare documentatie, compleet met parameterbeschrijvingen, voorbeeldcode en type-informatie.
• Ondersteuning van ontwikkeltools: Veel moderne IDE's (Integrated Development Environments) en editors gebruiken JSDoc-commentaren om IntelliSense en andere code-hulpmiddelen te bieden, wat de ontwikkelervaring verbetert.

JSDoc vs TypeScript

JSDoc is niet alleen geweldig voor documentatie; het is ook een uitstekend alternatief voor JavaScript-projecten die geen gebruik maken van TypeScript of voor oudere projecten. Met JSDoc kan je type-informatie aan je JavaScript-code toevoegen via speciale commentaarblokken, wat de leesbaarheid en onderhoudbaarheid van de code verbetert.

Veel moderne IDE's en teksteditors, zoals Visual Studio Code, begrijpen JSDoc-commentaren en kunnen IntelliSense, autocompletie en inline documentatie bieden op basis van deze commentaren. Dit kan de ontwikkelervaring aanzienlijk verbeteren zonder over te schakelen naar TypeScript.

Een groot voordeel van JSDoc is dat je geen build- of compilatiestap nodig hebt. Je schrijft gewoon JavaScript met JSDoc-commentaren en er is geen extra tooling nodig om de code uit te voeren. Dit in tegenstelling tot TypeScript, dat moet worden getranspilleerd naar JavaScript voordat het kan worden uitgevoerd.

Beperkingen van JSDoc ten opzichte van TypeScript

JSDoc is een alternatief, maar kan TypeScript niet volledig vervangen. TypeScript biedt enkele voordelen die JSDoc niet heeft:

• Statische typecontrole: TypeScript voert statische typecontrole uit tijdens de compilatie, wat helpt bij het vroegtijdig opsporen van typefouten.
• Geavanceerde typefuncties: TypeScript biedt geavanceerde typefuncties, zoals union types, intersection types en generics.
• ES6+ features: TypeScript ondersteunt moderne JavaScript-functies, wat helpt bij het schrijven van modernere JavaScript-code.
• Breed framework-ondersteuning: TypeScript wordt ondersteund door de meeste moderne Front-End frameworks.

De implementatie van JSDoc in een JavaScript-project

JSDoc is gemakkelijk te integreren en kan via een npm-package worden geïnstalleerd. Met een configuratiebestand bepaal je wat er gedocumenteerd wordt en hoe dit eruit komt te zien. Je kunt ook configureren dat .vue of .jsx bestanden opgenomen worden in de gegenereerde documentatie.

Om type-checking via JSDoc beschikbaar te maken binnen Visual Studio Code moet er wel een setting toegevoegd worden aan de settings.json van Visual Studio Code.

"js/ts.implicitProjectConfig.checkJs": true, 

Als we nu voor deze functie een type in JSDoc definiëren, zal er een linting error worden getoond als er niet het juiste type wordt meegegeven zoals gedefinieerd in het JSDoc commentaarblok, zoals we dat ook kennen bij TypeScript.

Basistypes in JSDoc

Het toevoegen van JSDoc in een .js-bestand, gebeurt door middel van een commentaarblok dat begint met /**. Bijvoorbeeld:

  // comment binnen javascript 
  /* comment binnen javascript */ 
 
  /** 
   * comment binnen javascript met JSDoc 
   */ 

Door het ‘@type’ mee te geven, kunnen we net zoals bij TypeScript laten weten welk type we verwachten.

/** 
   * This represents the name of the owner 
   * @type {string} 
   */ 
  const ownerName = 'ShareValue' 

Uiteraard kunnen we ook een array definiëren. Net als bij TypeScript kan dat of met ‘Array’ of door string[] mee te geven als type.

/** 
   * the avalible car colors for the car 
   * @type {Array<string>} 
   */ 
  const carColor = ['red', 'blue', 'green'] 

Het maken van een objecttype kan worden bereikt door gebruik te maken van de ‘@typedef’ richtlijn waarmee we het object creëren en met ‘@property’ specificeren binnen het object.

  /** 
   * * @typedef {Object} Person - a person schema 
   * @property {number} id 
   * @property {string} name 
   * @property {number|string} age 
   * @property {string} email 
   * @property {string[]} family 
   */ 
 
  /** @type {Person} */ 
  const person = { 
    id: 847, 
    name: 'Kees', 
    email: 'person@test.nl', 
    age: 40, 
    family: ['Toon', 'Sandra'] 
  } 

Ook bij functies kan je in de documentatie het return-type meegeven door een ‘@returns’ toe te voegen aan het commentaarblok.

  /** 
   * Sum of two numbers.  
   * @param {number} number1 - The number to be divided. 
   * @param {number} number2 - The number to divide by. 
   * @returns {number} The result of the division. 
   */ 
  const sumNumbers = (number1, number2) => { 
    return number1 + number2 
  } 

Op deze manier kunnen we ook bijvoorbeeld classes, constructors en methods voorzien van documentatie en type safety.

JSDoc en Storybook

Storybook is een open-sourcetool voor het ontwikkelen van UI-componenten in isolatie. Hiermee kan je componenten onafhankelijk maken en presenteren, waardoor het eenvoudiger wordt om ze te testen en documenteren. Het add-on-ecosysteem van Storybook verbetert de mogelijkheden ervan verder, waardoor uitgebreide documentatie mogelijk is.

Door JSDoc te integreren met Storybook biedt dit verschillende voordelen:

1. Verbeterde documentatie: Automatisch gedetailleerde componentdocumentatie genereren, wat handmatige updates vermindert en consistentie garandeert.
2. Verbeterde ontwikkelaarservaring: Ontwikkelaars hebben directe toegang tot componentdetails, inclusief props, typen en gebruiksvoorbeelden.
3. Consistentie: Onderhoud één bron van waarheid voor documentatie, waardoor de kans op discrepanties tussen code en documentatie wordt verkleind.
4. Efficiëntie: Bespaar tijd door gebruik te maken van geautomatiseerde tools om documentatie te genereren en bij te werken.

Een interessante add-on voor storybook is: storybook-addon-jsdoc-to-mdx Deze Storybook-add-on scant je project automatisch op JavaScript- of TypeScript-bestanden, extraheert JSDoc-opmerkingen en genereert uitgebreide MDX-documentatie. Het integreert naadloos met Storybook en verbetert je componentdocumentatie met gedetailleerde inzichten en voorbeelden die rechtstreeks uit uw broncode zijn geëxtraheerd.

Een voorbeeld:

/**
 * Interface representing a person with an optional age property.
 */
interface Person {
  name: string;
  age?: number;
}

/**
* Function that prints a person's name and optionally age if provided.
* @param {Person} person The person.
*/
function printPerson(person: Person): void {
  console.log(`Name: ${person.name}`);
  if (person.age !== undefined) {
      console.log(`Age: ${person.age}`);
  }
}

Resulteert in de volgende Storybook documentatie:

Bron: (storybook-addon-jsdoc-to-mdx)

Conclusie

Voor het ontwikkelen van applicaties is het gebruik van TypeScript nog steeds de weg vooruit. Echter, als je vooral bezig bent met het ontwikkelen van libraries, dan is het gebruik van JavaScript in combinatie met JSDoc een goed alternatief. Zeker in combinatie met Storybook biedt dit een krachtige oplossing. Voor bestaande projecten die in JavaScript zijn gebouwd en te kostbaar zijn om om te bouwen naar TypeScript, blijft JSDoc een zeer waardevolle tool.

Door JSDoc te integreren in je workflow, profiteer je van gedetailleerde en consistente documentatie, verbeterde leesbaarheid van de code en een soepelere ontwikkelervaring. En dat zonder dat je hoeft over te schakelen naar een volledig nieuwe taal of framework.

Ook aan de slag met JSDoc?

Ben je benieuwd hoe JSDoc interessant kan zijn voor jouw project of kan je onze expertise gebruiken bij de implementatie? Ons team van experts staat klaar om je te ondersteunen. Of je nu meer informatie wilt over de mogelijkheden van JSDoc, advies nodig hebt over de beste aanpak voor het project of hulp zoekt bij de integratie: wij helpen je graag verder. Neem vandaag nog vrijblijvend contact met ons op en we bespreken de mogelijkheden!