Automatic Documentation

Document Without Interrupting Development

Everyone agrees that documentation is necessary, yet almost no one writes it. Why? Because writing happens at the worst possible time: the feature is finished, and attention has already moved on. Codex shifts this cost. It analyzes the code as it exists and produces complete, up-to-date documentation that aligns with the actual implementation. This fidelity is the deciding factor: invented documentation causes more harm than a blank page because it inspires false confidence.

Inline Documentation: JSDoc and Comments

The most consulted documentation appears right in the editor’s tooltip, exactly where the question arises.

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

Here is what Codex produces for a price calculation function:

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

Two pieces of information here are worth everything else: the unit—cents, not euros—and the exception thrown for negative values. These are precisely the two things a developer usually discovers in production, after billing customers ten times less than intended. Codex extracted them from the implementation, not from a generic comment template.

Generating a README

For a new project, or for a README that has become fictional due to drift, list what the reader must be able to do once they finish reading.

"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 relies on package.json, configuration files, and the actual directory tree to produce a document that reflects the project’s current state. The instruction “without values” is not a whim: without it, an agent that just read a well-populated .env.example might happily copy values you do not want appearing in a versioned file.

API Documentation

For a REST API, the most cost-effective documentation is what other tools can consume without human intervention.

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

Everything is extracted from the code: route paths, HTTP methods, validation schemas, and response types. The resulting specification is therefore faithful to the implementation, allowing your consumers to derive a typed client or a test collection without asking you a single question.

Architecture Documentation

Architecture decisions are rarely written down. When they are, they describe the initial intent rather than the reality three years later. Ask Codex to formalize what actually exists in the 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"

This document has an unexpected secondary benefit: by describing module dependencies as they truly are, it exposes couplings no one had acknowledged—such as the billing service importing a utility from the authentication module.

Updating Existing Documentation

Outdated documentation is worse than no documentation because it wastes time with authority.

"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 confronts every claim in the README against the actual code and corrects inconsistencies. Schedule this task periodically, such as before every release, rather than discovering its necessity the day a new hire finds that none of the installation commands work.

Automating via AGENTS.md

To stop treating documentation as a separate chore, make it a permanent constraint of the project.

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

With these three rules, every development task carries its own documentation update. The gap between code and description stops widening silently, which is the only sustainable way to win this battle.

Key Takeaways

• Codex generates documentation faithful to the actual code, not invented
• Inline documentation (JSDoc) is the most useful for daily work
• Codex can produce READMEs, OpenAPI specs, and architecture documentation
• Use Codex to detect and correct outdated documentation
• Add documentation rules to AGENTS.md to automate the process