Documentation Generator

documentation-generator

Purpose

Produce documentation whose source of truth is the code, not a separate document that starts accurate and rots. The input is a codebase, a module, or an API spec; the output is doc comments in the source, a generated reference site, a README, a changelog, or a diagram — plus an honest list of what is still undocumented.

Documentation that is written beside the code drifts within weeks. Documentation derived from the code drifts only when someone changes a signature without changing its comment — which a generator can detect and report. That detection is most of the value here; typing prose is the cheap part.

When to use

• A public API has no reference docs, or its docs are stale after a refactor
• Doc comments are missing on public symbols and the toolchain warns about it
• An OpenAPI spec exists and the human-readable REST docs do not
• A release needs a changelog and the commits follow a convention
• A new contributor needs a README or an architecture overview to orient themselves

Not this skill:

• Writing a design doc, proposal, or spec with the user → doc-coauthoring
• Looking up documentation for a third-party library → find-docs
• A whole-project audit that happens to flag documentation gaps → code-analyzer
• Hand-drawing a specific diagram rather than deriving one → draw-io-diagram-generator
• Converting existing documents between formats → markitdown

Prerequisites

1. What is being documented, and which toolchain already owns it? Detect from build files, not from file extensions — the doc toolchain is declared there, and a project that already has one has already made most of the decisions.

Load one stack reference plus, when the task needs it, project-docs.md. Loading all of them mixes idioms from toolchains that are not in play and buries the ones that are.

2. What documentation already exists? Read the current docs before generating anything — a docs/ directory, an existing README, three or four already-documented public symbols. Their voice, depth, and structure are already decided; matching them matters more than any convention in this skill. A generated page that reads nothing like its neighbours will be rewritten by hand.

# existing docs, doc config, and the conventions already in use
ls -d docs doc site .docc *.docc 2>/dev/null
find . -maxdepth 2 \( -name 'Doxyfile*' -o -name 'mkdocs.yml' -o -name 'dokka*' \
  -o -name '*.docc' -o -name 'cliff.toml' -o -name 'redocly.yaml' \) -not -path '*/build/*'

3. Is the code stable enough to document? Documenting an API that is about to change wastes the work twice. If the target is mid-refactor, say so and offer to document the parts that are settled.

Workflow

Step 1: Decide what the reader needs

Documentation fails far more often from wrong altitude than from bad prose. Pick the type from who is reading and what they are trying to do:

The last row matters: a guide cannot be derived from signatures, because the ordering and the motivation live in the author's head. When the user asks for one, either gather that context from them or hand off to doc-coauthoring.

Step 2: Find what is undocumented

Let the toolchain answer this instead of reading files: every stack has a warning for missing docs on public symbols. The stack reference gives the exact switch — #![warn(missing_docs)] in Rust, public_member_api_docs in Dart, WARN_IF_UNDOCUMENTED in Doxygen, and so on.

Rank the gaps rather than filing them alphabetically:

1. Public API surface first. What callers cannot see, they do not need documented.
2. Entry points before leaves. The type someone constructs first earns a comment before its private helper does.
3. Non-obvious behavior before obvious behavior. Units, threading, nullability, ownership, error conditions, and side effects are what readers actually come for.

A comment restating the signature (/** Returns the name. */ on getName()) is noise: it adds maintenance cost and no information. Skip it, and say you skipped it and why.

Step 3: Write the doc comments

Write in the source, in the stack's markup, with its tags — the stack reference has the syntax and the idioms. Across all of them, the same things separate a useful comment from filler:

• Lead with the contract, not the mechanism. What it guarantees, not how it is implemented — implementations change, contracts are what callers depend on.
• Document what the signature cannot say: units, valid ranges, nullability, thread/isolate/actor affinity, ownership and lifetime, whether it blocks, whether it is idempotent.
• Every error path a caller must handle — thrown exceptions, Err variants, failed futures, non-zero returns — with the condition that produces it.
• Compilable examples where the toolchain supports them — rustdoc doc-tests, KDoc @sample, DocC snippets, Doxygen @snippet. These are the only examples that cannot silently go stale, because CI fails when they break.
• Link, do not repeat. Every toolchain has intra-doc links; a duplicated explanation is a second copy to keep true.

Write for the caller who has the signature in front of them and still has a question.

Step 4: Generate and check the output

Run the generator and read its warnings — broken links, undocumented symbols, and unresolved references are exactly the drift this skill exists to catch. The stack reference has the command.

Two checks worth doing every time:

• Do the examples compile and run? Run the doc-tests where the toolchain has them. An example that does not compile is worse than no example.
• Do the links resolve? Broken intra-doc links usually mean a symbol was renamed and its references were not — a drift signal, not a formatting nit.

Keep the output small: doc generators are verbose, so filter to warnings and errors rather than pasting the whole run. Never read the generated site back into context — it is build output, and the source comments are the thing under review.

Step 5: Report what is documented and what is not

## Documentation added
<files touched, and what each now documents>

## Generated
<command run, output location, and the real result — including warning count>

## Still undocumented
<specific public symbols or endpoints, as `file:line` — with why, where there is a reason>

## Drift found
<docs that contradict the implementation, if any>

The drift section is the one people act on. A comment that describes behavior the code no longer has is worse than a missing comment, because it is believed. Report it even when fixing it is out of scope.

Operations

Critical constraints

• Never document behavior you have not read. A plausible-sounding comment on code you skimmed is a confident lie that outlives the person who wrote it. Read the implementation, or ask.
• Never invent API surface — endpoints, parameters, error codes, or config keys that are not in the code or the spec. Readers trust docs more than they trust code, which makes fabrication here unusually expensive.
• Do not modify implementation code while documenting it. Renaming for clarity or "fixing" what a comment reveals is a separate change; propose it, do not slip it in.
• Do not commit generated output unless the project already does — check for docs/api/, target/doc/, or doc/api/ in .gitignore first. Committed generated docs go stale in review.
• Never put credentials, internal hostnames, customer data, or unreleased product names in examples. Documentation is the most-published artifact a repo has; use the toolchain's own placeholder conventions.
• Do not delete existing documentation to make room for generated docs. Hand-written docs usually encode context no generator can recover — merge, or ask.
• Do not fabricate a changelog entry for a commit you cannot interpret. List it as-is under an "Other" heading and let the human classify it.

References

• kotlin-kmp.md — KDoc tags, Dokka setup and tasks, per-source-set docs for KMP, @sample, expect/actual documentation
• flutter-dart.md — dartdoc comments, dart doc, macros and templates, pub.dev metadata, doc lints
• swift-apple.md — DocC markup, .docc catalogs, Topics, tutorials, swift package generate-documentation, static hosting
• rust-cpp.md — rustdoc, doc-tests, intra-doc links, docs.rs metadata; Doxygen, Breathe/Sphinx
• api-specs.md — OpenAPI/Swagger linting, generating reference sites and Markdown, documenting a spec that already exists
• other-languages.md — TSDoc/TypeDoc, Python docstrings and Sphinx/MkDocs, Go doc comments
• project-docs.md — README scaffolding, conventional-commit changelogs, architecture diagrams in Mermaid, versioned docs sites