Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Documentation automatique

Lektion 8 av 20 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Documenter sans interrompre le développement
  2. Documentation inline : JSDoc et commentaires
  3. Générer un README
  4. Documentation d’API
  5. Documentation d’architecture
  6. Mettre à jour la documentation existante
  7. Automatiser via AGENTS.md
  8. Viktiga punkter

Documenter sans interrompre le développement

Tout le monde s’accorde à dire que la documentation est nécessaire, pourtant presque personne ne la rédige. Pourquoi ? Parce que l’écriture intervient au pire moment : la fonctionnalité est terminée et l’attention s’est déjà déplacée ailleurs. Codex déplace ce coût. Il analyse le code tel qu’il existe et produit une documentation complète et à jour, alignée sur l’implémentation réelle. Cette fidélité est le facteur décisif : une documentation inventée cause plus de dégâts qu’une page blanche, car elle inspire une fausse confiance.

Documentation inline : JSDoc et commentaires

La documentation la plus consultée apparaît directement dans l’infobulle de l’éditeur, exactement là où la question se pose.

"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."

Voici ce que Codex produit pour une fonction de calcul de prix :

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

Deux informations ici valent tout le reste : l’unité (centimes, pas euros) et l’exception levée pour les valeurs négatives. Ce sont précisément les deux choses qu’un développeur découvre généralement en production, après avoir facturé les clients dix fois moins que prévu. Codex les a extraites de l’implémentation, pas d’un modèle de commentaire générique.

Générer un README

Pour un nouveau projet, ou pour un README devenu fictif à force de dérive, liste ce que le lecteur doit pouvoir faire une fois sa lecture terminée.

"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 s’appuie sur le package.json, les fichiers de configuration et l’arborescence réelle des répertoires pour produire un document reflétant l’état actuel du projet. L’instruction « without values » (sans valeurs) n’est pas un caprice : sans elle, un agent qui vient de lire un fichier .env.example bien rempli pourrait copier allègrement des valeurs que tu ne veux pas voir apparaître dans un fichier versionné.

Documentation d’API

Pour une API REST, la documentation la plus rentable est celle que d’autres outils peuvent consommer sans intervention humaine.

"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."

Tout est extrait du code : chemins des routes, méthodes HTTP, schémas de validation et types de réponse. La spécification résultante est donc fidèle à l’implémentation, permettant à tes consommateurs de dériver un client typé ou une collection de tests sans te poser la moindre question.

Documentation d’architecture

Les décisions d’architecture sont rarement écrites. Quand elles le sont, elles décrivent l’intention initiale plutôt que la réalité trois ans plus tard. Demande à Codex de formaliser ce qui existe réellement dans le code.

"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"

Ce document présente un avantage secondaire inattendu : en décrivant les dépendances entre modules telles qu’elles sont réellement, il expose des couplages que personne n’avait reconnus, comme le service de facturation important un utilitaire depuis le module d’authentification.

Mettre à jour la documentation existante

Une documentation obsolète est pire que l’absence de documentation, car elle fait perdre du temps avec autorité.

"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 confronte chaque affirmation du README au code réel et corrige les incohérences. Planifie cette tâche périodiquement, par exemple avant chaque release, plutôt que de découvrir sa nécessité le jour où un nouveau collaborateur constate qu’aucune commande d’installation ne fonctionne.

Automatiser via AGENTS.md

Pour cesser de traiter la documentation comme une corvée séparée, fais-en une contrainte permanente du projet.

## 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

Avec ces trois règles, chaque tâche de développement emporte sa propre mise à jour documentaire. L’écart entre le code et sa description cesse de se creuser silencieusement, ce qui est la seule façon durable de gagner cette bataille.

Viktiga punkter

  • Codex génère une documentation fidèle au code réel, pas inventée
  • La documentation inline (JSDoc) est la plus utile pour le travail quotidien
  • Codex peut produire des README, des spécifications OpenAPI et une documentation d’architecture
  • Utilise Codex pour détecter et corriger la documentation obsolète
  • Ajoute des règles de documentation dans AGENTS.md pour automatiser le processus