Automating Code Documentation with AI

Documentation is the broccoli of software development. Everyone knows they should do it. Nobody wants to do it. And the stuff that exists is usually stale, incomplete, or written by someone who already understood the code so well that the docs are useless to anyone who doesn’t.

AI doesn’t make documentation exciting. But it does make it nearly effortless. Here’s how I’ve been using it to keep docs actually useful and actually current.

The Documentation Problem

Most documentation fails for one of three reasons: it’s never written, it’s written once and never updated, or it describes what the code does instead of why. AI can help with all three, but with different approaches for each.

JSDoc and TSDoc Generation

This is the lowest-hanging fruit. Paste a function into AI, ask for JSDoc, and you get back documentation that’s usually 90% correct. But the key is asking for the right kind of documentation.

Bad approach: “Add JSDoc to this function.” This produces docs that just restate the code.

Better approach: “Add JSDoc to this function. Focus on: why this function exists, what business logic it implements, any non-obvious behavior, and what callers should know about error handling.”

/**
 * Calculates the pro-rated subscription cost when a user upgrades
 * mid-billing cycle. Uses the remaining days in the current period
 * to determine the credit from their existing plan.
 *
 * @param currentPlan - The user's active subscription plan
 * @param newPlan - The plan they're upgrading to
 * @param billingCycleStart - Start date of the current billing period
 * @returns The amount to charge for the upgrade, accounting for
 *          unused time on the current plan. Returns 0 if the new
 *          plan costs less (downgrades are handled by applyDowngrade).
 * @throws {BillingError} If either plan has invalid pricing data
 *
 * @example
 * // User upgrades from Basic ($10/mo) to Pro ($25/mo) on day 15 of 30
 * calculateProration(basicPlan, proPlan, cycleStart)
 * // Returns: $7.50 (half-month of $15 price difference)
 */

That’s documentation that actually helps the next developer. The AI wrote it. I spent 30 seconds reviewing it.

README Generation

For new packages or modules, I give AI the entry point file and any config, then ask for a README. The prompt that works best for me:

Generate a README for this module that includes:
1. What problem it solves (one paragraph)
2. Quick start example
3. API reference for exported functions
4. Configuration options
5. Common pitfalls or gotchas

Write it for a developer who's joining the team next week.
Don't explain JavaScript basics. Do explain our project-specific patterns.

The “write it for a new team member” framing consistently produces better results than generic documentation. It forces the AI to include context that existing team members take for granted.

API Documentation

REST API docs are tedious to write and critical to maintain. I’ve found that feeding AI my route handlers produces accurate endpoint documentation with request/response examples. Combined with TypeScript types for the request and response bodies, the AI generates documentation that stays close to the actual implementation.

The workflow: change the route handler, paste the updated code, regenerate that endpoint’s docs. It takes 60 seconds per endpoint instead of 10 minutes of manually updating an OpenAPI spec.

Architecture Documentation

This is where AI needs the most human oversight. AI can describe what your architecture looks like by analyzing code, but it can’t explain why you made certain decisions. I use a hybrid approach:

• AI generates the structural overview (“The system has three layers: API routes, service layer, data access”)
• I add the decision rationale (“We chose this layering because our service layer needs to be reusable across REST and GraphQL endpoints”)
• AI formats and polishes the final document

The result is architecture docs that are both accurate and meaningful. The AI handles the tedious descriptive parts. I handle the parts that require institutional knowledge.

When AI Docs Need Human Editing

AI-generated documentation has consistent blind spots:

• It over-documents obvious things. A parameter named userId doesn’t need a description that says “The ID of the user.” I routinely trim these.
• It misses business context. AI can see that a function checks if a date is a weekend, but it can’t know that this is because your billing system doesn’t process payments on weekends.
• It’s overly formal. AI docs tend to sound like textbooks. I edit them to match our team’s voice, which is more casual and direct.
• It guesses at intent. When AI isn’t sure why code exists, it makes something up that sounds plausible. Always verify the “why” sections.

Keeping Docs in Sync

The real power of AI documentation isn’t the initial generation. It’s the updates. When I change a function’s behavior, I paste the updated code and ask AI to update the existing docs. This takes seconds, which means it actually happens. Manual documentation updates take minutes, which means they get deferred to “later” and later never comes.

Some teams integrate this into their PR workflow: if a file changes, the AI generates updated docs as part of the review. This isn’t perfect, but it’s infinitely better than the alternative, which is docs that were accurate six months ago and haven’t been touched since.

Documentation doesn’t have to be a chore. With AI handling the mechanical parts, you can focus on the parts that matter: the why, the context, and the gotchas that only a human who’s been in the codebase would know.