Automatic Documentation with AI

Generate professional documentation in seconds with artificial intelligence

Why Document with AI

Documentation is what everyone hates writing but everyone needs to read. AI can generate docstrings, READMEs, API docs, and technical comments in seconds, saving you hours of tedious work.

Types of Documentation AI Generates

1. Docstrings / JSDoc

"Generate JSDoc for this function:

[code]

Include:
- Description of what it does
- @param with types and description
- @returns with type and description
- @throws for errors
- @example with practical usage"

2. Project README

"Generate a professional README.md for this project:

[file structure + package.json]

Include:
- Title and description
- Key features
- Step-by-step installation
- Usage with examples
- Required environment variables
- Available scripts
- Contributing
- License"

3. API Documentation

"Generate OpenAPI/Swagger documentation for these endpoints:

[Express routes code]

YAML format. Include:
- Description of each endpoint
- Parameters (path, query, body)
- Responses (200, 400, 404, 500)
- Request/response examples
- Required authentication"

Practical Examples

Before: Undocumented function

async function process(data, opts) {
  if (!data || !data.length) return [];
  const filtered = data.filter(d => d.active);
  const sorted = filtered.sort((a, b) => b.score - a.score);
  return sorted.slice(0, opts?.limit || 10);
}

After: Documented by AI

/**
 * Processes and filters a list of items, returning the
 * most relevant ones sorted by score.
 *
 * @param {Array<Object>} data - List of items to process
 * @param {Object} [opts] - Configuration options
 * @param {number} [opts.limit=10] - Maximum number of items to return
 * @returns {Array<Object>} Active items sorted by score (desc)
 *
 * @example
 * const users = [{ name: 'Ana', active: true, score: 95 }];
 * const top = await process(users, { limit: 5 });
 * // => [{ name: 'Ana', active: true, score: 95 }]
 */
async function process(data, opts) { ... }

Prompt for Complete Documentation

"Document this complete code:

[code]

Generate:
1. Docstrings for each function/class
2. Inline comments for complex logic
3. README with installation and usage
4. Contributing guide
5. Changelog template

Format: [JSDoc/Python docstrings/Markdown]"

Best Practices

Always review: AI can invent parameters
Keep it updated: Regenerate when you change code
Be specific: Indicate the documentation format
Include examples: Ask for real usage examples
Document errors: @throws, possible exceptions

Structure of a Good README

The README is the business card of your project. A good README not only explains what your code does, but guides the reader from initial curiosity to installation and usage in minutes. AI can generate professional READMEs if you provide the right structure and essential project information.

Professional README template

This template includes all sections that successful open source projects use. Adapt it based on your project's complexity: not every project needs all sections, but the essential ones (description, installation, usage) are mandatory.

# Project Name

[Version badge] [License badge] [CI/CD badge] [Coverage badge]

> Short and catchy one-line project description.

## Features

- Feature 1 with brief description
- Feature 2 with brief description
- Feature 3 with brief description

## Installation

```bash
git clone https://github.com/user/project
cd project
npm install
cp .env.example .env
npm run dev
```

## Usage

### Basic example
```javascript
import { feature } from './project';
const result = feature(input);
```

### Advanced configuration
```javascript
const config = { option1: true, option2: 'value' };
const result = feature(input, config);
```

## Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| API_KEY  | API key | Yes | - |
| PORT     | Server port | No | 3000 |

## Scripts

| Script | Description |
|--------|-------------|
| npm run dev | Start development server |
| npm test | Run tests |
| npm run build | Generate production build |

## Contributing
1. Fork the project
2. Create your branch (git checkout -b feature/new-feature)
3. Commit (git commit -m 'Add new feature')
4. Push (git push origin feature/new-feature)
5. Open a Pull Request

## License
MIT

Prompt to generate README with AI

To get a quality README, provide the AI with all relevant project information. The more context you give, the more precise and useful the result will be.

"Generate a professional README.md for my project. Here's the information:

Name: TaskFlow API
Description: REST API for task management with JWT authentication
Stack: Node.js, Express, TypeScript, PostgreSQL, Prisma
Structure:
  src/
    routes/     - API routes
    controllers/ - Business logic
    middleware/  - Auth, validation, error handling
    models/     - Prisma schemas
    utils/      - Helpers and constants

Main endpoints:
- POST /auth/register - User registration
- POST /auth/login - Login
- GET /tasks - List tasks (paginated, filters)
- POST /tasks - Create task
- PUT /tasks/:id - Update task
- DELETE /tasks/:id - Delete task

Environment variables: DATABASE_URL, JWT_SECRET, PORT
Scripts: dev, build, test, migrate, seed

Include:
- Badges for npm version, license, CI status
- Architecture diagram in text
- Request/response examples with curl
- Docker deployment section
- Contributing guide"

API Documentation with OpenAPI/Swagger

OpenAPI (formerly Swagger) is the industry standard for documenting REST APIs. A well-written OpenAPI specification allows generating interactive documentation, SDK clients automatically, and request validation. AI is exceptional at generating OpenAPI specifications from your code.

AI-generated OpenAPI specification

The OpenAPI YAML format is verbose but structured. AI can generate the entire specification if you provide your API routes and data models.

# Example of AI-generated OpenAPI specification
openapi: 3.0.3
info:
  title: TaskFlow API
  version: 1.0.0
  description: REST API for task management

paths:
  /api/tasks:
    get:
      summary: List tasks
      tags: [Tasks]
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, in_progress, done]
      responses:
        '200':
          description: Task list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  total: { type: integer }
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    Task:
      type: object
      properties:
        id: { type: string, format: uuid }
        title: { type: string, maxLength: 200 }
        status:
          type: string
          enum: [pending, in_progress, done]
        createdAt: { type: string, format: date-time }

Prompt to generate complete OpenAPI

"Generate the complete OpenAPI 3.0 specification for these Express routes:

[all routes code]

Data models:
[models/schema code]

Include:
- All endpoints with their HTTP methods
- Path, query, and body parameters with correct types
- All possible responses (200, 201, 400, 401, 404, 500)
- Reusable schemas in components
- Request and response examples
- Security: bearerAuth for protected endpoints
- Tags to group endpoints by resource
- Detailed description of each endpoint

Format: YAML"

Automated Documentation Tools

There are specific tools for each language and ecosystem that generate documentation from code comments. AI can help you write comments in the correct format and configure these tools to generate always-up-to-date documentation.

JSDoc / TypeDoc (JavaScript/TypeScript)

JSDoc is the documentation standard for JavaScript. TypeDoc extends JSDoc for TypeScript, leveraging type information to generate richer documentation. Both generate navigable static websites from your comments.

// Prompt for the AI:
"Generate complete JSDoc for this module, compatible with TypeDoc:

[code]

For each function/class include:
- @description brief and @description detailed
- @param with types, name, and description
- @returns with type and description
- @throws for each possible error
- @example with functional code
- @see with links to related documentation
- @since with version number
- @deprecated if applicable, with suggested alternative

TypeDoc configuration for tsconfig.json:
{
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs",
    "theme": "default"
  }
}"

Sphinx (Python)

Sphinx is the standard documentation tool for Python, used by projects like Django, Flask, and NumPy. It generates HTML, PDF, and EPUB documentation from docstrings and reStructuredText files.

# Prompt for the AI:
"Generate Google-style docstrings for this Python module,
compatible with Sphinx and the napoleon extension:

[Python code]

For each function/class:
- Args with type and description
- Returns with type and description
- Raises for each exception
- Examples with executable doctests
- Notes with additional information

Sphinx configuration (conf.py):
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon',
              'sphinx.ext.viewcode', 'sphinx.ext.doctest']"

Other useful tools

In addition to language-specific tools, there are documentation generators that work for multiple ecosystems and can complement your workflow.

Swagger UI: Renders OpenAPI specifications as interactive documentation where you can test endpoints directly from the browser
Docusaurus: Meta's framework for creating modern documentation sites with React, ideal for projects that combine guides, API docs, and blog
MkDocs + Material: Markdown documentation generator with Material Design theme, very popular in Python and DevOps projects
Storybook: Interactive UI component documentation that allows visualizing and testing components in isolation with different props
Postman / Insomnia: API documentation automatically generated from request collections, with examples and integrated tests

Frequently Asked Questions

How much documentation is enough?

Essential minimum documentation includes: a README with description, installation, and basic usage; docstrings on all public functions and classes; API documentation for all endpoints; and a contributing guide if it's open source. As a general rule, a new developer should be able to start using your project in less than 15 minutes just by reading the documentation. If it takes longer, you need to improve the installation sections or usage examples.

How do I keep documentation up to date?

Outdated documentation is worse than no documentation. To keep it current: integrate doc generation into your CI/CD pipeline, add a documentation check to your pull requests (can't merge without updating docs if you change APIs), use tools like JSDoc or Sphinx that generate docs from code (if you change the code, docs regenerate), and establish the rule that every new feature requires documentation before merging.

Should I document private and internal functions?

Private functions don't need formal documentation (JSDoc, generated docstrings), but they should have a brief comment explaining what they do if the logic isn't obvious. Automatically generated documentation should focus on the public API: the functions, classes, and modules that other developers will consume. For internal code, a good function name and a one-line inline comment are usually sufficient.

Can AI generate documentation in multiple languages?

Yes, AI can generate documentation in any language. An effective strategy is to generate the main documentation in English (since it's the standard language in software development) and then ask AI to translate it to other languages. However, automatic translations of technical terms may not be accurate, so it's recommended that a native speaker review the translated documentation. For docstrings and code comments, always keep English as the primary language.