Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Documentatie automatisch genereren

Les 8 van 20 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Documenteren zonder de ontwikkeling te onderbreken
  2. Inline documentatie: JSDoc en commentaren
  3. Een README genereren
  4. API-documentatie
  5. Architectuurdocumentatie
  6. Bestaande documentatie bijwerken
  7. Automatiseren via AGENTS.md
  8. Belangrijkste punten

Documenteren zonder de ontwikkeling te onderbreken

Iedereen is het erover eens dat documentatie noodzakelijk is, toch schrijft bijna niemand het. Waarom? Omdat het schrijven op het slechtst mogelijke moment plaatsvindt: de functionaliteit is afgerond en de aandacht is alweer verschoven. Codex verlegt deze kosten. Het analyseert de code zoals die bestaat en produceert volledige, actuele documentatie die overeenkomt met de daadwerkelijke implementatie. Deze nauwkeurigheid is de doorslaggevende factor: verzonnen documentatie richt meer schade aan dan een lege pagina, omdat het een vals vertrouwen wekt.

Inline documentatie: JSDoc en commentaren

De meest geraadpleegde documentatie verschijnt direct in de tooltip van de editor, precies daar waar de vraag ontstaat.

"Add JSDoc documentation to all exported functions 
and types in src/lib/. Include a description, 
parameters, return type, and a usage example 
for each function."

Dit is wat Codex produceert voor een functie voor prijsberekening:

/**
 * Calculates the total price after applying the discount.
 * 
 * @param basePrice - Unit price in cents
 * @param quantity - Number of units (minimum 1)
 * @param discountPercent - Discount percentage (0-100)
 * @returns The total price in cents, rounded to an integer
 * 
 * @example
 * calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
 * 
 * @throws {ValidationError} If price or quantity is negative
 */
export function calculateTotal(
  basePrice: number,
  quantity: number,
  discountPercent: number = 0
): number {
  // ...
}

Twee informatiepunten hier zijn meer waard dan al de rest: de eenheid—cent, niet euro—en de uitzondering die wordt gegenereerd bij negatieve waarden. Dit zijn precies de twee dingen die een ontwikkelaar meestal pas in productie ontdekt, nadat klanten tien keer minder zijn gefactureerd dan de bedoeling was. Codex heeft deze gegevens geëxtraheerd uit de implementatie, niet uit een generiek commentaarsjabloon.

Een README genereren

Voor een nieuw project, of voor een README die door veroudering fictief is geworden, somt u op wat de lezer moet kunnen doen zodra hij de tekst heeft gelezen.

"Generate a comprehensive README.md for this project. Include:
- Project description and purpose
- Prerequisites (Node.js, PostgreSQL, etc.)
- Step-by-step installation instructions
- Required environment variables (without values)
- Available commands (dev, test, build, lint)
- Project structure
- How to contribute"

Codex baseert zich op package.json, configuratiebestanden en de daadwerkelijke directorystructuur om een document te produceren dat de huidige staat van het project weerspiegelt. De instructie “without values” is geen gril: zonder deze zou een agent die zojuist een goed gevuld .env.example heeft gelezen, zonder aarzelen waarden kopiëren die u niet in een versiebeheerd bestand wilt zien verschijnen.

API-documentatie

Voor een REST-API is de meest kosteneffectieve documentatie die welke andere tools kunnen verwerken zonder menselijke tussenkomst.

"Analyze all routes in src/api/routes/ and generate 
an openapi.yaml file. Include request and response 
schemas based on existing TypeScript types and 
Zod validations."

Alles wordt uit de code gehaald: routepaden, HTTP-methoden, validatieschema’s en responstypes. De resulterende specificatie is derhalve trouw aan de implementatie, waardoor uw consumenten een getypte client of een testcollectie kunnen afleiden zonder u ook maar één vraag te stellen.

Architectuurdocumentatie

Architectuurbeslissingen worden zelden opgeschreven. Als dat wel gebeurt, beschrijven ze de oorspronkelijke intentie in plaats van de realiteit drie jaar later. Vraag Codex om te formaliseren wat er daadwerkelijk in de code bestaat.

"Analyze the project architecture and create a 
docs/architecture.md file documenting:
- Layers (API, services, repositories, models)
- Data flow for a typical request
- Patterns used (repository pattern, dependency injection)
- Dependencies between modules"

Dit document heeft een onverwacht nevenvoordeel: door de module-afhankelijkheden te beschrijven zoals ze werkelijk zijn, legt het koppelingen bloot die niemand had erkend—zoals de facturatieservice die een utility importeert uit de authenticatiemodule.

Bestaande documentatie bijwerken

Verouderde documentatie is erger dan geen documentatie, omdat het tijd verspillt met autoriteit.

"Compare README.md with the current state of the project. 
Identify outdated sections (commands that no longer exist, 
removed dependencies, incorrect instructions). 
Update the README accordingly."

Codex confronteert elke bewering in de README met de daadwerkelijke code en corrigeert inconsistenties. Plan deze taak periodiek in, bijvoorbeeld voor elke release, in plaats van de noodzaak ervan te ontdekken op de dag dat een nieuwe medewerker merkt dat geen enkele installatieopdracht werkt.

Automatiseren via AGENTS.md

Om te voorkomen dat documentatie als een aparte klus wordt behandeld, maakt u er een permanente beperking van het project van.

## Documentation
- Every new exported function MUST have complete JSDoc
- API changes MUST update openapi.yaml
- Comment format: French for business logic, English for technical details

Met deze drie regels bevat elke ontwikkelingstaak zijn eigen documentatie-update. De kloof tussen code en beschrijving houdt op stilletjes groter te worden, wat de enige duurzame manier is om deze strijd te winnen.

Belangrijkste punten

  • Codex genereert documentatie die trouw is aan de daadwerkelijke code, niet verzonnen
  • Inline documentatie (JSDoc) is het nuttigst voor het dagelijkse werk
  • Codex kan README’s, OpenAPI-specificaties en architectuurdocumentatie produceren
  • Gebruik Codex om verouderde documentatie te detecteren en corrigeren
  • Voeg documentatieregels toe aan AGENTS.md om het proces te automatiseren