Documentation automatique

Documenter sans interrompre le développement

Tout le monde s’accorde sur la nécessité de documenter et presque personne ne le fait, parce que l’écriture arrive au pire moment : la fonctionnalité est finie, l’attention est ailleurs. Codex déplace ce coût. Il analyse le code tel qu’il est et produit une documentation complète, à jour, cohérente avec l’implémentation réelle. Cette fidélité est le point décisif : une documentation inventée fait davantage de dégâts qu’une page blanche, puisqu’elle inspire confiance.

Documentation inline : JSDoc et commentaires

La documentation la plus consultée est celle qui apparaît dans l’infobulle de l’éditeur, à l’endroit exact où la question se pose.

"Ajoute la documentation JSDoc à toutes les fonctions 
et types exportés dans src/lib/. Inclus la description, 
les paramètres, le type de retour, et un exemple d'usage 
pour chaque fonction."

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

/**
 * Calcule le prix total après application de la remise.
 * 
 * @param basePrice - Prix unitaire en centimes
 * @param quantity - Nombre d'unités (minimum 1)
 * @param discountPercent - Pourcentage de remise (0-100)
 * @returns Le prix total en centimes, arrondi à l'entier
 * 
 * @example
 * calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
 * 
 * @throws {ValidationError} Si le prix ou la quantité est négatif
 */
export function calculateTotal(
  basePrice: number,
  quantity: number,
  discountPercent: number = 0
): number {
  // ...
}

Deux informations valent ici tout le reste : l’unité — des centimes, non des euros — et l’exception levée en cas de valeur négative. Ce sont précisément les deux choses qu’un développeur découvre d’ordinaire en production, après avoir facturé cent fois trop peu. Codex les a extraites de l’implémentation, pas d’un modèle générique de commentaire.

Générer un README

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

"Génère un README.md complet pour ce projet. Inclus :
- Description du projet et son but
- Prérequis (Node.js, PostgreSQL, etc.)
- Instructions d'installation étape par étape
- Variables d'environnement nécessaires (sans les valeurs)
- Commandes disponibles (dev, test, build, lint)
- Structure du projet
- Comment contribuer"

Codex s’appuie sur le package.json, les fichiers de configuration et l’arborescence réelle pour produire un document qui reflète l’état du projet. La précision « sans les valeurs » n’est pas une coquetterie : sans elle, un agent qui vient de lire un .env.example bien rempli recopiera volontiers des valeurs que vous ne souhaitez pas voir apparaître dans un fichier versionné.

Documentation d’API

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

"Analyse toutes les routes dans src/api/routes/ et génère 
un fichier openapi.yaml. Inclus les schemas de requête et 
de réponse basés sur les types TypeScript et les validations 
Zod existantes."

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

Documentation d’architecture

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

"Analyse l'architecture du projet et crée un fichier 
docs/architecture.md qui documente :
- Les couches (API, services, repositories, modèles)
- Le flux de données pour une requête typique
- Les patterns utilisés (repository pattern, dependency injection)
- Les dépendances entre modules"

Ce document a une vertu secondaire qu’on n’attendait pas : en décrivant les dépendances entre modules telles qu’elles sont, il rend visibles des couplages que personne n’avait assumés — le service de facturation qui importe un utilitaire du module d’authentification, par exemple.

Mettre à jour la documentation existante

Une documentation obsolète est pire que pas de documentation, parce qu’elle fait perdre du temps avec autorité.

"Compare le README.md avec l'état actuel du projet. 
Identifie les sections obsolètes (commandes qui n'existent 
plus, dépendances supprimées, instructions incorrectes). 
Mets à jour le README en conséquence."

Codex confronte chaque affirmation du README au code réel et corrige les incohérences. Programmez cette tâche périodiquement, avant chaque release par exemple, plutôt que de la découvrir nécessaire le jour où un nouvel arrivant constate qu’aucune des commandes d’installation ne fonctionne.

Automatiser via AGENTS.md

Pour que la documentation cesse d’être un chantier séparé, faites-en une contrainte permanente du projet.

## Documentation
- Toute nouvelle fonction exportée DOIT avoir une JSDoc complète
- Les modifications d'API DOIVENT mettre à jour openapi.yaml
- Format des commentaires : français pour le métier, anglais pour le technique

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

Points clés à retenir

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