How to Document Code With AI

Quick Answer

Paste your function, class, or module and ask AI to write documentation in your preferred format. For READMEs, describe what the project does and AI handles the structure. AI covers the tedious 80% of documentation. Your job is to add the nuance.

What This Workflow Helps You Do

• Write docstrings and inline comments faster
• Generate README files for new projects
• Document an existing codebase that lacks documentation
• Produce consistent documentation style across a team

Step-by-Step Process

Step 1: Write docstrings for functions (5 minutes)

Write docstrings for these [language] functions using [docstring format].

[paste your functions]

For each function include:
- One-line summary of what it does
- Args/Parameters: name, type, description for each
- Returns: type and description
- Raises: any exceptions that can be thrown and when
- A brief usage example if the function is non-obvious

Use [Google style / NumPy style / JSDoc / JavaDoc] format.

Step 2: Write a README for a project (10 minutes)

Write a README for this project.

Project name: [name]
What it does: [1-2 sentence description]
Tech stack: [languages, frameworks, major dependencies]
Who uses it: [target users or audience]

Please generate a README with these sections:
- Project title and one-line description
- What it does (2-3 sentences, non-technical)
- Prerequisites (what needs to be installed)
- Installation instructions (step by step)
- Basic usage with a code example
- Configuration options (if any)
- Contributing guide (brief)
- License

Use standard Markdown formatting.

Step 3: Add inline comments to complex code (5 minutes)

Add inline comments to this [language] code to explain the non-obvious parts.

[paste your code]

Rules for the comments:
- Only comment the WHY, not the WHAT (don't say "increment i" for i++)
- Comment complex algorithms, non-obvious logic, and workarounds
- Don't comment every line — only where a reader would need explanation
- Keep comments concise — one line if possible
- Flag any code that seems unclear and might benefit from refactoring instead

Return the commented version of the code.

Step 4: Document an API (10 minutes)

Write API documentation for these endpoints.

[paste your API routes/controllers]

For each endpoint provide:
- HTTP method and URL
- One-sentence description
- Request parameters (path, query, body) with types and descriptions
- Request body example (if applicable)
- Response format with field descriptions
- Response example (success)
- Error responses and when they occur

Format as clean Markdown documentation.

Step 5: Generate a changelog entry (5 minutes)

Write a changelog entry for these code changes.

Changes made:
[describe or paste the diff/changes]

Follow the Keep a Changelog format:
- Version: [version number]
- Date: [today's date]
- Sections: Added / Changed / Fixed / Removed (only include relevant ones)

Keep entries concise and from the user's perspective — what changed for someone using this code?

Documentation Checklist

• All public functions have docstrings with parameter and return types
• Complex logic has inline comments explaining why, not what
• README covers installation, usage, and configuration
• README has a working code example
• API endpoints are documented with request and response examples
• Changelog is updated for significant changes

Common Mistakes

Commenting the obvious. // increment counter adds noise, not value. Comment things that would take a reader more than 5 seconds to understand.

Not reviewing AI documentation for accuracy. AI reads the code correctly most of the time but can misunderstand intent, especially for edge cases. Read every docstring before committing.

Writing documentation once and never updating it. Documentation that’s wrong is worse than no documentation. Build a habit of updating docs alongside code changes.