Documentation automatique

Documenter sans interrompre le développement

La documentation est essentielle mais souvent négligée. Codex peut analyser votre code et générer une documentation complète, à jour, et cohérente avec l’implémentation réelle.

Documentation inline : JSDoc et commentaires

La documentation la plus utile est celle qui vit à côté du code :

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

Résultat de Codex :

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

Codex lit l’implémentation, comprend la logique, et produit une documentation fidèle au comportement réel — pas une documentation inventée.

Générer un README

Pour un nouveau projet ou un README obsolète :

"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 analyse le package.json, les fichiers de configuration, la structure des dossiers, et génère un README qui reflète l’état réel du projet.

Documentation d’API

Pour les APIs REST, Codex peut générer la documentation au format OpenAPI :

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

Codex extrait les informations directement du code : les chemins des routes, les méthodes HTTP, les schémas de validation, les types de réponse. Le résultat est une spécification OpenAPI fidèle à l’implémentation.

Documentation d’architecture

Pour les décisions d’architecture, demandez à Codex de formaliser ce qui existe 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"

Mettre à jour la documentation existante

La documentation obsolète est pire que pas de documentation :

"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 vérifie chaque affirmation du README contre le code réel et corrige les incohérences.

Automatiser via AGENTS.md

Ajoutez une règle dans votre AGENTS.md pour que Codex documente automatiquement :

## 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 cette règle, chaque tâche de développement inclura automatiquement la mise à jour de la documentation.

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