Auto-Generating Docs with Cursor Agent

Your open-source library just hit 10,000 stars on GitHub. The most upvoted issue? “Please add documentation.” The README has a single code example from two years ago, there are no API docs, the architecture is entirely in the lead developer’s head, and a major v2.0 release ships next week with 40 breaking changes. You need comprehensive docs — API reference, getting started guide, migration guide, architecture overview — and you need them before the release.

Writing documentation from scratch is one of the most tedious tasks in software development. Reading documentation that someone else should have written is one of the most frustrating. Cursor bridges this gap by reading your codebase and generating accurate, structured documentation that you can then refine with human judgment. The AI handles the mechanical extraction — function signatures, parameter types, return values, example generation — while you handle the editorial work of making it clear and useful.

What You’ll Walk Away With

• A codebase analysis prompt that identifies every public API and generates JSDoc/TSDoc annotations
• An architecture documentation prompt that produces Mermaid diagrams from code structure
• A getting-started guide generator that creates step-by-step tutorials from working tests
• A migration guide prompt that diffs two versions and generates a breaking changes document
• A documentation freshness workflow that detects when docs fall out of sync with code

The Workflow

Step 1: Audit existing documentation gaps

Before generating anything, understand what exists and what is missing. Use Ask mode for a gap analysis.

Tip

Copy-paste prompt — Documentation gap analysis:

@src @README.md @docs

Analyze this codebase and create a documentation gap report:

1. List every public function, class, and type that is exported from the package entry point
2. For each, check if it has: JSDoc/TSDoc comments, parameter descriptions, return type documentation, usage examples
3. Rate documentation completeness: fully documented, partially documented, undocumented
4. Identify the 10 most-used functions (by import count across the codebase) that lack documentation
5. Check if architecture documentation exists (system diagrams, data flow, component relationships)
6. Check if onboarding documentation exists (getting started, installation, basic usage)
7. Check if there is a changelog or migration guide

Format as a prioritized list: what should be documented first based on usage frequency and user impact?

Step 2: Generate JSDoc annotations for the public API

The fastest documentation win is adding inline documentation to your source code. Agent mode can read function implementations and generate accurate JSDoc comments.

Tip

Copy-paste prompt — JSDoc generation:

@src/index.ts @src/lib

Add comprehensive JSDoc/TSDoc documentation to every exported function, class, and type in this package:

For each export:

1. Write a one-line summary of what it does
2. Add @param tags with descriptions for every parameter
3. Add @returns tag describing the return value
4. Add @throws tag for any errors the function can throw
5. Add @example with a realistic, working code example (not a trivial placeholder)
6. Add @since tag with the version where this API was introduced (check git blame)
7. Add @see tags linking to related functions

Rules:

• Read the implementation to understand behavior — do not guess from the function name alone
• Examples should be copy-paste runnable, including necessary imports
• If a function has non-obvious behavior (edge cases, implicit coercion, mutation), document it explicitly
• Do not document private/internal functions — only the public API

Step 3: Generate architecture documentation

Architecture docs rot faster than any other type of documentation because they require understanding the system as a whole, not just individual functions. The trick is generating them from the code itself so they can be regenerated when the architecture changes.

@src

Generate architecture documentation at docs/architecture.md:

1. System Overview: A Mermaid diagram showing the major modules and their dependencies
2. Data Flow: How data moves through the system from input to output
3. Key Abstractions: The 5 most important interfaces/types and what they represent
4. Extension Points: Where users can customize or extend the library (plugins, hooks, callbacks)
5. Design Decisions: Why the code is structured this way (infer from the patterns -- why does it use a pipeline architecture? why are there separate parse and transform phases?)
6. Performance Characteristics: Big-O complexity of key operations, memory usage patterns

Use Mermaid for all diagrams. Keep the document under 1000 words -- architecture docs that
nobody reads are worse than no architecture docs.

Step 4: Create a getting started guide from tests

Your test suite is a gold mine of working code examples. Agent can extract them and turn them into a tutorial.

Tip

Copy-paste prompt — Getting started guide:

@tests @src/index.ts

Create a Getting Started guide at docs/getting-started.md by analyzing the test suite:

1. Installation: Show npm/yarn/pnpm install commands
2. Basic Usage: Extract the simplest test case that demonstrates the core functionality. Turn it into a step-by-step tutorial with explanations.
3. Common Patterns: Find the 5 most common usage patterns across all test files. Document each with a code example and explanation.
4. Configuration: Document all configuration options with their defaults and what they control
5. Error Handling: Show the error types the library can throw and how to handle each
6. TypeScript: Show how types flow through the API — what to import, how generics work

Every code example must be a complete, runnable snippet (including imports). Test each example mentally: would it actually compile and run if someone pasted it?

Write for a developer who has never seen this library before but is experienced with the language and ecosystem.

Step 5: Generate a migration guide for breaking changes

For major version releases, a migration guide is the difference between users upgrading smoothly and users staying on the old version forever.

@git

Generate a v1-to-v2 migration guide at docs/migration-v2.md:

1. Run `git diff v1.0.0..HEAD -- src/` to see all code changes
2. Identify every breaking change:
   - Renamed functions or parameters
   - Changed return types
   - Removed APIs
   - Changed default values
   - New required parameters
3. For each breaking change, show:
   - What the v1 code looked like
   - What the v2 code should look like
   - A one-line explanation of why the change was made
4. Group changes by category: API changes, type changes, behavior changes, removed features
5. Add a "Quick Migration" section with find-and-replace patterns for the most common changes
6. Add a "Codemods" section if any changes can be automated

Order from most common to least common -- the change that affects the most users goes first.

Step 6: Set up documentation freshness monitoring

Documentation that falls out of sync with code is worse than no documentation — it actively misleads. Set up automated checks.

Tip

Copy-paste prompt — Documentation CI:

Create a documentation freshness check for the CI pipeline:

1. Add a script at scripts/check-docs.ts that:

   • Extracts all code examples from markdown files in docs/
   • Compiles each TypeScript example to verify it is valid
   • Runs each executable example and verifies it does not throw
   • Checks that every function referenced in docs actually exists in the source
   • Reports: which examples are broken, which functions are referenced but do not exist

2. Add a pre-commit check that warns when:

   • A public API function signature changes but its JSDoc was not updated
   • A new export is added to src/index.ts without documentation
   • A documented function is deleted without updating the docs

3. Add these checks to the GitHub Actions workflow:

   • Run on every PR
   • Block merge if code examples fail to compile
   • Warn (but don’t block) on missing documentation for new exports

Create the script, the pre-commit hook, and the CI workflow step.

Generating Diagrams with Mermaid

Cursor can generate Mermaid diagrams that render directly in GitHub, GitLab, and most documentation tools. For complex systems, break diagrams into focused views.

@src

Generate these Mermaid diagrams for the architecture docs:

1. Module Dependency Graph: Show which modules import from which other modules.
   Use subgraphs for logical groupings (core, plugins, utils).

2. Request Lifecycle: A sequence diagram showing how a typical request flows
   through the system from entry point to response.

3. State Machine: If there are any state transitions (connection states, transaction
   states, etc.), generate a state diagram.

4. Class Hierarchy: Show inheritance and composition relationships between
   the key classes/interfaces.

Output as fenced mermaid code blocks that I can paste directly into markdown files.

When This Breaks

Generated docs describe what the code does, not why. The AI can read the implementation and explain the mechanics, but it cannot know the business context. Always review generated docs and add the “why” yourself — why does this function exist? What problem does it solve? When should a user reach for this instead of that?

Code examples do not actually run. The AI generates examples that look correct but have import errors, missing setup code, or assume context that is not present. The documentation CI check from Step 6 catches these, but during initial generation, always test the first few examples manually.

Architecture diagrams become unreadable. For large codebases, a full dependency graph is an unreadable hairball. Tell the AI to focus on a specific subsystem or limit the diagram to top-level modules. “Show me the top 10 most-imported modules and their relationships” is more useful than “show me everything.”

Migration guide misses subtle behavior changes. The AI detects API signature changes reliably but struggles with behavior changes where the function signature stays the same but the output changes. Supplement the automated migration guide with a manually written “Behavior Changes” section for anything you know changed but the code does not explicitly show.

Documentation generation bloats the codebase. Generated docs can be verbose. Set a word budget in your prompts (“Keep under 500 words”) and edit aggressively after generation. A concise doc that people actually read is infinitely more valuable than a comprehensive doc that nobody opens.

JSDoc annotations get stale. Inline documentation rots just like external docs. The pre-commit hook from Step 6 detects when function signatures change without documentation updates, but it cannot detect when the behavior changes while the signature stays the same. Periodic re-generation (monthly or per-release) catches drift.

What’s Next

Lessons Overview Return to the full list of 20 real-world development scenarios.

Code Review Enhancement Use Cursor to catch documentation gaps during code review.

Custom Rules and Templates Create .cursor/rules that enforce documentation standards across your team.