write-documentation

Writing Good Rust Documentation

This consolidated skill covers all aspects of writing high-quality rustdoc:

1. Voice & Tone - Serious, meaningful, precise, and fun
2. Prose Style - Opening lines, explicit subjects, verb tense
3. Structure - Inverted pyramid principle
4. Links - Intra-doc link patterns
5. Constants - Human-readable numeric literals
6. Formatting - Markdown tables and cargo rustdoc-fmt

When to Use

Proactively (While Writing Code)

• Writing new code that includes /// or //! doc comments
• Creating new modules, traits, structs, or functions
• Adding links to other types or modules in documentation
• Defining byte/u8 constants

Retroactively (Fixing Issues)

• /fix-intradoc-links - Fix broken links, convert inline to reference-style
• /fix-comments - Fix constant conventions in doc comments
• /fix-md-tables - Fix markdown table formatting
• /docs - Full documentation check and fix

---

Voice & Tone

r3bl is serious & meaningful & precise. r3bl is also fun.

Documentation should be rigorous about content, playful about presentation:

Aspect	Serious & Precise	Fun
Technical accuracy	Correct terminology, proper distinctions	-
Links	Intra-doc links, authoritative sources	-
Visual aids	ASCII diagrams, tables	Emoji for scannability
Language	Clear, unambiguous	Literary references, personality

Examples

Emoji for visual scanning (semantic, not decorative):

//! 🐧 **Linux**: Uses `epoll` for I/O multiplexing
//! 🍎 **macOS**: Uses `kqueue` (with PTY limitations)
//! 🪟 **Windows**: Uses IOCP for async I/O

Severity with visual metaphors:

//! 1. 🐢 **Multi-threaded runtime**: Reduced throughput but still running
//! 2. 🧊 **Single-threaded runtime**: Total blockage - nothing else runs

Literary references with layered meaning:

//! What's in a name? 😛 The three core properties:

The 😛 is a visual pun on "tongue in cheek" - Shakespeare's Juliet argues names don't matter, but here we use the quote to explain why RRT's name does matter. The emoji signals the irony.

Rule: Emoji must have semantic meaning (OS icons, severity levels). Never use random 🚀✨🎉 for "excitement."

Unicode Over Emoji in Diagrams

For ASCII art diagrams in rustdoc, use only glyphs listed in docs/boxes.md. That file is the approved set - every glyph there has been tested across multiple fonts and terminals on macOS, Linux, and Windows. Emoji and other Unicode characters outside that set may render with incorrect widths or as tofu boxes.

Box-Drawing Characters

See docs/boxes.md for the complete approved set. Common patterns:

┌─────────────────────────────────────────────────────────────────────────┐
│                         Box with header                                 │
├─────────────────────────────────────────────────────────────────────────┤
│   Content here                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Arrows

Use	Instead of	Unicode
→	➡️	U+2192 RIGHTWARDS ARROW
←	⬅️	U+2190 LEFTWARDS ARROW
▼	⬇️	U+25BC BLACK DOWN-POINTING TRIANGLE
▲	⬆️	U+25B2 BLACK UP-POINTING TRIANGLE
►	▶️	U+25BA BLACK RIGHT-POINTING POINTER
◄	◀️	U+25C4 BLACK LEFT-POINTING POINTER

Status/Result Indicators

Use	Instead of	Unicode	Meaning
■	✅ ✓	U+25A0 BLACK SQUARE	Success/yes
□	❌ ✗ ✘	U+25A1 WHITE SQUARE	Failure/no

Example: Before and After

// ❌ Bad: Emoji may not render correctly
//! Timeline: create ──► spawn ──► ❌ fails

// ■ Good: Font-safe Unicode renders everywhere
//! Timeline: create ──► spawn ──► □ fails

Exception: OS-identifying emoji (🐧 🍎 🪟) are acceptable in prose because they're semantic and commonly supported. But in ASCII art diagrams, stick to standard Unicode.

---

Prose Style

Doc comments should read naturally and have clear subjects. Avoid abrupt sentence starts.

Dashes: Use Regular Dashes, Not Em Dashes

Always use regular dashes (-) instead of em dashes (—) in all documentation.

• Em dashes (—, U+2014) have no dedicated keyboard key - they require compose sequences, Unicode input, or copy-paste, which creates friction for contributors.
• In monospace fonts (terminals, editors), em dashes and regular dashes are nearly indistinguishable, so the typographic benefit is lost.
• Searching for - won't find — and vice versa, making grep/search harder.

// ❌ Bad: Em dash (can't type from keyboard)
/// This is the main trait — implement it to add your logic.

// ✅ Good: Regular dash (just type it)
/// This is the main trait - implement it to add your logic.

Escape Sequences: Use ESC Notation, Not \x1B

In documentation prose, write escape sequences using human-readable ESC notation, not Rust hex escape syntax.

• \x1B is Rust/C escape syntax for byte 27. In prose, it forces the reader to mentally decode hex before understanding the sequence.
• ESC is the standard terminal notation used in VT-100 specs, Wikipedia, and terminal documentation. A reader instantly knows "escape byte" without hex decoding.
• Space-separate the components (ESC [ A, not ESC[A) so each part (escape prefix, intermediary, final byte) is visually distinct.

// ❌ Bad: Rust escape syntax in documentation prose
/// Sends `\x1BOA` in application mode or `\x1B[A` in normal mode.
/// The detector scans for `\x1B[?1h` and `\x1B[?1l`.

// ✅ Good: Standard terminal notation
/// Sends `ESC O A` in application mode or `ESC [ A` in normal mode.
/// The detector scans for `ESC [ ? 1 h` and `ESC [ ? 1 l`.

Exception: In Rust code, doctests, and byte literals, continue using \x1B or 0x1B - that's actual Rust syntax the compiler needs.

Acronym Formatting: Always Backtick

All technical acronyms get backticks. No exceptions - treat them as technical identifiers, not prose.

// ❌ Bad: Plain text acronyms
/// Uses ANSI escape sequences to parse PTY output via the VTE parser.

// ✅ Good: All acronyms backticked
/// Uses `ANSI` escape sequences to parse `PTY` output via the `VTE` parser.

When Linking: Use [`ACRONYM`]

When a backticked acronym has a useful link target, wrap it in [ ] to create a reference-style intra-doc link. Prefer local links when the target is a dependency in Cargo.toml (validated at build time, works offline, version-matched). Fall back to external URLs (Wikipedia, man pages) only when no local target exists:

/// Parses [`PTY`] output using the [`VTE`] parser over [`SSH`] connections.
///
/// [`PTY`]: https://en.wikipedia.org/wiki/Pseudoterminal   // No local target
/// [`VTE`]: mod@vte                                        // Local dep in Cargo.toml
/// [`SSH`]: https://en.wikipedia.org/wiki/Secure_Shell     // No local target

Common linked acronyms and their targets:

Acronym	Link Target	Source
[`TUI`]	crate::tui::TerminalWindow::main_event_loop	Local (crate item)
[`VTE`]	mod@vte	Local (Cargo.toml dep)
[`PTY`]	https://en.wikipedia.org/wiki/Pseudoterminal	External (OS concept)
[`SSH`]	https://en.wikipedia.org/wiki/Secure_Shell	External (protocol)
[`TCP`]	https://en.wikipedia.org/wiki/Transmission_Control_Protocol	External (protocol)
[`DCS`]	Spec URL or crate path as appropriate	Depends on context

Without a Link: Plain Backticks

When used inline without a link target, plain backticks are sufficient:

/// The `CSI` sequence `ESC [ 38 ; 5 ; n m` sets 256-color foreground.
/// This `SGR` parameter handles `RGB` true color via `ANSI` escape codes.

Common unlinked acronyms: `SGR`, `CSI`, `OSC`, `ANSI`, `ASCII`, `RGB`, `UTF-8`, `EOF`, `FIFO`.

Software Product and Project Names

Software names are technical identifiers and get backticks:

// ❌ Bad: Plain text product names
/// Compatible with xterm, Alacritty, and kitty terminals.

// ✅ Good: Backticked product names
/// Compatible with `xterm`, `Alacritty`, and `kitty` terminals.

Common product names: `xterm`, `Alacritty`, `kitty`, `GNOME VTE`, `st` (suckless terminal).

When linking to an external project: [`GNOME VTE`]: https://gitlab.gnome.org/GNOME/vte

What Stays Plain Text

Standards body names and specification document identifiers stay as plain text - they are citation references, not technical identifiers:

Category	Examples
Spec document identifiers	ECMA-48, ITU-T Rec. T.416, ISO 8613-6

When linking a spec, use descriptive link text: [ITU-T Rec. T.416]: https://...

DEC Private Modes

DEC private mode mnemonics are acronyms and get backticks: `DECAWM`, `DECSC`, `DECRC`, `DECSM`.

When linking to a crate constant: [`DECAWM`]: crate::DECAWM_AUTO_WRAP

Opening Lines by Item Type

The first line/paragraph of a doc comment should describe what the item IS, not what it does. Follow Rust std conventions.

IMPORTANT: The first paragraph must be separate. Rustdoc uses it as the summary in:

• Module listings (each item shows only its first paragraph)
• IDE tooltips and autocomplete
• Search results

// ❌ Bad: Summary and details merged
/// A trait for creating workers. This trait implements two-phase setup.

// ✅ Good: Summary is separate paragraph
/// A trait for creating workers.
///
/// This trait implements two-phase s

---

*Content truncated.*