# Documentation generator

## Purpose

Generate or update documentation for code. Supports three scopes: a single file, a directory, or the full project. Always matches the documentation style already present in the codebase.

### Returns

Generated documentation written to disk (docstrings inserted into source files, README updates, or new doc files in `docs/`, depending on scope). Plus structured metadata for downstream skills: the scope, the list of files modified or created, the documentation style detected, and a per-file count of how many functions, classes, or sections were documented. A composing skill (a doc site builder, a coverage check) can read these directly.

If you want documentation specifically for new developers joining a project (setup steps, prerequisites, env vars), see the [onboarding checklist skill](/articles/skill-onboarding-checklist/) instead. This skill produces API and code-level documentation; the onboarding skill produces a setup guide.

## When to use

- The user asks to document a file, module, or project
- The user asks to update the README
- The user asks to add docstrings, JSDoc, or inline comments
- The user asks to generate an API reference

## When not to use

- The codebase has no consistent documentation style and the user hasn't picked one. Generating docs in three different conventions across the same project is worse than no docs.
- The target file or directory doesn't exist. The skill detects this and stops, but worth declining at invocation.
- The project's docs are auto-generated from a different source (typedoc from TypeScript types, sphinx-autodoc from Python). Hand-written docstrings will conflict with the generated output. Hand off and let the existing pipeline do its job.
- The user wants developer-onboarding documentation rather than API documentation. Use the [onboarding checklist skill](/articles/skill-onboarding-checklist/).

## Inputs

- **scope**: one of `file`, `directory`, or `project`
- **target**: path to the file or directory (ignored for project scope, defaults to repo root)

## Steps

### 1. Analyze existing documentation style

Before writing anything, study what already exists.

- For file scope: read the target file and 2-3 nearby files in the same directory. Note the docstring format (JSDoc, Google-style Python docstrings, Rust doc comments, etc.), level of detail, and tone.
- For directory scope: read the directory's README or index file if one exists. Sample 3-5 files to understand the module's purpose and conventions.
- For project scope: read the root README.md, CONTRIBUTING.md, and any docs/ directory. Note which sections exist, their heading style, and formatting conventions.

If no existing documentation exists, use these defaults:

- Python: Google-style docstrings
- TypeScript/JavaScript: JSDoc with `@param`, `@returns`, `@throws`
- Rust: `///` doc comments with examples
- Go: standard godoc format
- Other languages: block comments above functions with param/return descriptions

### 2. Read the code

- For file scope: read the entire target file.
- For directory scope: list all source files in the directory. Read each one.
- For project scope: identify the project structure by reading the top-level directory listing, package manifest (package.json, pyproject.toml, Cargo.toml, go.mod), and entry points. Read key source files (not every file, focus on public interfaces and main modules).

Build a mental model of:

- What the code does (purpose, inputs, outputs)
- Public API surface (exported functions, classes, types)
- Dependencies and relationships between modules
- Commands (scripts in package.json, Makefile targets, CLI entry points)

### 3. Detect manually-written sections

Before generating any documentation, identify sections that a human wrote intentionally. These must be preserved exactly as-is.

Markers of manually-written content:

- Sections with prose paragraphs (not just auto-generated lists)
- Content between `<!-- manual-start -->` and `<!-- manual-end -->` comment markers
- Sections titled "Contributing", "License", "Acknowledgments", "Philosophy", "Why this exists"
- Any section containing links to external resources, blog posts, or discussions
- Content that references specific decisions, tradeoffs, or history

When you encounter these sections, preserve them verbatim in their original position.

### 4. Generate documentation

#### File scope

Add or update documentation for every public function, class, method, type, and constant. For each:

- Write a one-line summary of what it does
- Document parameters with types and descriptions
- Document return values
- Document thrown exceptions or error conditions
- Add a brief usage example if the function's purpose is not obvious from its name

Do NOT add documentation to:

- Private/internal helper functions that are self-explanatory (under 5 lines, clear name)
- Import statements
- Simple constant assignments where the name says it all

Place documentation in the position conventional for the language (above the definition for most languages).

#### Directory scope

Generate or update the directory's README.md with:

- One-paragraph module description
- List of public files and what each contains
- Usage example showing how to import and use the module
- Any configuration or setup needed

Then apply file scope documentation to each source file in the directory.

#### Project scope

Generate or update the root README.md with these sections (skip any that don't apply):

1. **Project name and one-line description** (from package manifest or existing README)
2. **What it does** (2-3 sentences, derived from reading the code)
3. **Getting started** (install commands, prerequisites)
4. **Usage** (primary commands, basic examples)
5. **Architecture** (file/directory structure with one-line descriptions)
6. **Configuration** (environment variables, config files)
7. **Development** (how to run tests, dev server, build)
8. **API reference** (if the project exposes a programmatic API, summarize it here or link to generated docs)

Preserve all manually-written sections identified in step 3. Insert them in their original positions.

For the Architecture section, generate a tree view like:

```
src/
  components/    # Reusable UI components
  pages/         # Route handlers
  utils/         # Shared helper functions
  config.ts      # App configuration
```

### 5. Verify nothing broke

After writing documentation:

- If the project has a build command (found in package.json scripts, Makefile, etc.), run it. Documentation changes should not break builds, but template literals in docstrings or malformed comments can cause syntax errors.
- If the project has a linter configured, run the lint command.
- If either command fails, read the error, fix the documentation that caused it, and run again.

Report what was generated: number of files documented, sections added to README, and whether the build/lint passed.

## Output format

Summarize what was done:

```
Documented 12 functions across 4 files.
Updated README.md: added Architecture and Development sections.
Preserved 2 manually-written sections (Contributing, Philosophy).
Build passed. Lint passed.
```

## Important rules

- NEVER delete or rewrite manually-written documentation sections
- NEVER generate documentation that contradicts the code (if a function returns a string, don't say it returns a number)
- NEVER add boilerplate filler ("This function is used to..." just say what it does)
- Keep the same tone as existing documentation. If the project uses casual language, don't switch to formal. If it uses formal language, don't switch to casual.
- If you are unsure about a function's purpose, say so briefly rather than guessing wrong