DEV Community

Jovan Chan
Jovan Chan

Posted on • Originally published at aicoderscope.com

Code Documentation with AI: From Inline Comments to Architecture Docs (2026)

#cursor #githubcopilot #cline #aider

This article was originally published on aicoderscope.com

Documentation debt compounds faster than technical debt. A function with zero comments is annoying; a 3,000-line service file with zero comments, written 18 months ago by someone who quit, is a project killer. AI coding tools have genuine leverage here — but only if you match the right tool to the right documentation level.

There are four distinct levels where AI can help, and each requires a different workflow:

  • Level 1: Inline comments (the why, not the what)
  • Level 2: Docstrings, JSDoc, and TSDoc
  • Level 3: README files and module-level docs
  • Level 4: Architecture Decision Records and system diagrams

This guide covers all four, with specific tool setups and honest assessments of where each breaks down.

Level 1: Inline comments

Inline comments are the most abused form of documentation. The failure mode AI makes worse, not better: generating comments that restate what the code already says.

# BAD — Copilot default behavior on obvious code
x = x + 1  # Increment x by 1
Enter fullscreen mode Exit fullscreen mode

That comment is noise. What you actually want is the why:

# Retry counter starts at 0; max 3 retries enforced downstream
x = x + 1
Enter fullscreen mode Exit fullscreen mode

AI cannot generate the why from code alone — that lives in your head, a Jira ticket, or a Slack thread from six months ago. What AI can do is prompt you to write it.

Cursor workflow for inline comments:

Open Cursor Chat (Cmd/Ctrl+L), select a block of code, and ask: "What would a new engineer need to know about this block that isn't obvious from reading it?" The response isn't the comment — it's a list of non-obvious facts. You pick the ones worth preserving and write them yourself. This takes 60 seconds per function and produces comments that survive future refactors.

Copilot /explain for unfamiliar code:

When you inherit code rather than write it, Copilot's /explain command (in VS Code Chat panel) works well as a first-pass comprehension tool. Select the block, type /explain, and it generates a plain-English walkthrough. The practical use: copy the explanation, strip the obvious parts, and add what's left as a block comment above the function. You edited the comment, so you'll understand it in six months.

The baseline rule that holds regardless of tool: never let AI write inline comments unsupervised on code you just wrote. It doesn't know why you wrote it — only you do.

Level 2: Docstrings, JSDoc, and TSDoc

This is where AI genuinely earns its keep. Function signatures contain the inputs and outputs; the docstring's job is to document the contract, constraints, and edge cases. AI can infer a strong first draft from the signature and body.

Cursor

In Cursor Chat, paste a function and ask: "Write a Google-style Python docstring for this function. Include Args, Returns, Raises, and note any constraints on input values." The key is specifying the docstring convention — Google, NumPy, reST — so output is consistent with the rest of the file.

For TypeScript/React components, ask for JSDoc with @param, @returns, and @example. Cursor's inline autocomplete will also pick up the pattern after a few manual docstrings and continue writing them as you type new functions.

GitHub Copilot

Microsoft's training module on documentation generation identifies two primary methods:

  1. Inline suggestion: Type """ (Python) or /** (JS/TS) above a function and wait. Copilot completes the docstring from context. Works best when the function name is descriptive and the body is under ~40 lines.

  2. Chat-based: Select the function, open Copilot Chat, type "Write a docstring for this function". More reliable than inline completion for complex functions with multiple return paths.

Copilot's docstrings tend to be accurate on the happy path but miss error conditions. After generating, always manually add Raises: or @throws entries for any exception the function can produce.

Aider

Aider's strength for docstrings is batch generation across a file or module. (If you're not set up with Aider yet, the Aider + Ollama setup guide covers installation and model selection.) The workflow:

  1. Launch aider with the target file: aider src/api/handlers.py
  2. Switch to ask mode: /ask
  3. Prompt: "Which functions in this file are missing docstrings or have incomplete ones?"
  4. Review the list, then switch to code mode: /code Add Google-style docstrings to the functions you identified. Preserve existing docstrings.

Aider commits automatically after the change, so you get a clean git history entry per batch. Use --no-auto-commits if you want to review before committing.

Cline

Cline's Plan/Act mode maps well to documentation tasks. In Plan mode, it analyzes your codebase and proposes a documentation strategy without touching files. In Act mode, it executes. Workflow:

  1. Open Cline, enable Plan mode (top toolbar toggle in VS Code extension)
  2. Prompt: "Audit the Python files in src/services/ and list functions with missing or stub docstrings"
  3. Review the plan Cline generates
  4. Switch to Act mode to write the actual docstrings

The advantage over Aider: Cline can navigate multiple files in one session without you specifying each one. The disadvantage: it's slower and more talkative — better for a weekend documentation sprint than an inline quick fix.

Level 3: README and module-level documentation

README quality is the fastest signal of project health to any new contributor. AI can write a passable skeleton in 90 seconds; the problem is the skeleton is always too generic.

The generic README trap

Ask any AI tool to "write a README for this project" and you get:

## Installation
npm install

## Usage
See examples below.

## Contributing
Pull requests welcome.
Enter fullscreen mode Exit fullscreen mode

That's not a README — it's a template placeholder with your project name inserted. The fix: feed the AI specific questions to answer, not an open-ended request.

Effective Cursor Agent prompt for README:

You are writing a README.md for a developer who knows nothing about this project.
Answer these specific questions from the codebase:
1. What problem does this solve in one sentence?
2. What are the 3 most common use cases?
3. What does someone need to have installed to run this (with versions)?
4. What is the one command to get a working dev environment?
5. What are the 2-3 non-obvious configuration options that trip people up?
Enter fullscreen mode Exit fullscreen mode

This produces a README with real content instead of scaffolding. You still rewrite the intro and add any context the AI can't infer — external dependencies, team conventions, production gotchas — but the structure is there.

Module-level docs with Aider

For large codebases, Aider's architect mode is the right tool for module-level documentation. Architect mode uses two models: one proposes the documentation structure, the other writes the actual content. Launch with aider --architect --model claude-sonnet-4-6 src/ and ask it to create a docs/modules.md mapping each module to its responsibility, public API, and key dependencies.

The output needs human editing — AI doesn't know which modules are stable vs. experimental, or which are deprecated-but-still-imported — but generating the first draft from code analysis takes 3 minutes instead of 3 hours.

Level 4: Architecture Decision Records

ADRs are the highest-value documentation artifact and the hardest to generate with AI. An ADR captures not just what architecture decision was made, but why — what alternatives were considered, what trade-offs drove the choice, what context existed at the time.

AI can document the what. The why requires human input.

Setting up an ADR workflow with Cline

The most practical AI-assisted ADR workflow uses Cline to scan for undocumented architectural decisions

Top comments (0)