---
name: rust-module-documenter
description: "A complete markdown API reference for a Rust module, built from its source: overview, table of contents, a subsection with signature and description for every public item, and runnable examples where you want them. Use when a Rust module's public items need a markdown API reference with signatures, descriptions, and examples pitched at a chosen audience. Do not use for generating rustdoc comments inside the source, reviewing the module, or writing a README for the whole crate. Related topics: coding, rust."
---

# Rust Module Documenter

A complete markdown API reference for a Rust module, built from its source: overview, table of contents, a subsection with signature and description for every public item, and runnable examples where you want them.

## When to use

Use this skill when a Rust module's public items need a markdown API reference with signatures, descriptions, and examples pitched at a chosen audience. Do not use it for generating rustdoc comments inside the source, reviewing the module, or writing a README for the whole crate.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Extract every public item with its exact signature and existing doc comment, keeping accurate wording from the source.
3. Write the level-1 heading, a two-paragraph overview, and a table of contents linking to every section.
4. Give each item its own subsection with the signature in a rust code block and a description at the chosen style and audience level.
5. Add the selected extra sections, making every usage example compile as a doctest and listing each unsafe invariant under safety notes.
6. List private items in their own section only when requested, then check every link in the table of contents resolves.

## Inputs

- **Module source** (longer free text)
- **Include private items** (choose one: Yes, No)
- **Style** (choose one: Brief, Detailed, Mixed)
- **Audience** (choose one: Beginners, Intermediate, Advanced)
- **Extra sections** (choose any: Usage examples, Safety notes, Performance considerations, Compatibility notes)
- **Output file name** (free text, e.g. "module_docs.md")

## Output

A markdown document opening with a level-1 heading and table of contents, then one subsection per item with signature and description, then the selected extra sections.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Rust Module Documentation

Write markdown documentation for this Rust module.

- Module source: {{Module source}}
- Include private items: {{Include private items}}
- Style: {{Style}}
- Audience: {{Audience}}
- Extra sections: {{Extra sections}}
- Output file name: {{Output file name}}

Extract every public item with its exact signature and any existing doc comment, and keep the doc comment's wording where it is correct. Open with a level-1 heading matching the file name, a two-paragraph overview of what the module is for, and a table of contents that links to each section. Give each struct, enum, trait, and function its own subsection with the signature in a rust code block and a description at the chosen style: Brief is one sentence, Detailed covers parameters, return values, errors, and panics, Mixed is Detailed for functions and Brief for types. Pitch the prose at the audience: beginners get the ownership and error handling explained, advanced readers get the invariants and complexity. When usage examples are selected, make each one compile as a doctest. Safety notes list every unsafe block and the invariant the caller must uphold. List private items in a separate section only when requested.

Return the markdown document as plain text, starting with the level-1 heading that matches the file name without its extension.

## Pitfalls

- Paraphrasing a signature instead of copying it, so the documented types drift from the code.
- Writing usage examples that do not compile as doctests, which fail the moment someone runs cargo test.
- Documenting private helpers alongside public items without the toggle set, which clutters the reference and exposes internals.
