Documentation Generator

---
name: docs-gen
description: >
  Write JSDoc, docstrings, or TypeDoc-compatible annotations for functions,
  classes, and modules. Captures purpose, parameters, return value, thrown
  errors, and a short example. Use to bring a module up to documentation
  standards before a release, or to scaffold docs while a feature is still
  fresh in the author's mind.
when-to-use:
  - Backfilling docs on undocumented exports
  - Standardizing doc style across a package
  - Generating a public API reference from inline comments
  - Annotating a function before code review
---

# Documentation Generator

Run this skill on a file or module to receive inline documentation that
matches the project's existing convention.

## Overview

The skill detects the language and doc style from existing files in the
repo (JSDoc, TSDoc, reST, numpydoc, godoc, rustdoc), then generates
documentation blocks for every exported symbol. Each block contains:

- **Summary** — one sentence on what the symbol does.
- **Parameters** — name, type, meaning, with units/constraints where relevant.
- **Returns** — type and meaning; if it can be null/empty, when.
- **Throws** — each error class and the condition that triggers it.
- **Example** — the shortest runnable snippet that produces the documented
  output, copied verbatim from the test suite when possible.

It does **not** paraphrase the symbol name or restate obvious types; every
sentence earns its line.

## Usage examples

```bash
# Document every export in a file
npx skills run docs-gen --target src/api/users.ts

# Document a single function in JSDoc style
npx skills run docs-gen --target src/math.ts --fn addTax --style jsdoc

# Generate rustdoc for a whole module
npx skills run docs-gen --target src/lib.rs --style rustdoc --inline
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `target` | string | — | File or directory. |
| `fn` | string | — | Optional symbol name when `target` is a file. |
| `style` | enum | `auto` | `jsdoc`, `tsdoc`, `numpydoc`, `godoc`, `rustdoc`. |
| `inline` | bool | `false` | Edit the source file vs emit a separate `.md`. |
| `include_private` | bool | `false` | Document non-exported symbols too. |
| `example_from_tests` | bool | `true` | Lift an example from the test suite when one exists. |

## Expected output

Either an in-place patch (with a unified diff preview) or a new `*.md`
file. The summary includes the count of symbols documented, skipped
(private/legacy), and a list of any that lack enough context to document
reliably — those return `needs_human_review: true`.