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
7. ANSI Escape Codes - Spaced ESC [ notation (see ansi-escape-codes.md)

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:

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

Status/Result Indicators

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, En Dashes & Em Dashes: Do Not Use to Connect Sentences

The ASCII hyphen / hyphen-minus (-, U+002D) is the ONLY dash character permitted anywhere in the codebase. Non-ASCII en dashes (–) and em dashes (—, endash/emdash) are strictly forbidden.

Do NOT use hyphens (-), en dashes (–), or em dashes (—) to connect clauses or sentences in documentation.

• Connecting sentences or clauses with dashes, en dashes, or em dashes creates an awkward writing style.
• Use separate sentences or standard punctuation (colons, semicolons, commas, or parentheses) instead.
• Hyphens (-) should only be used for compound words (type-safe, zero-cost), markdown bullet points (- Item), or code/operators, never to join independent thoughts or clauses.

// ❌ Bad: Connecting sentences/clauses with dashes, en dashes, or em dashes
/// This is the main trait - implement it to add your logic.
/// This is the main trait – implement it to add your logic.
/// This is the main trait — implement it to add your logic.

// ✅ Good: Separate sentences or proper punctuation
/// This is the main trait. Implement it to add your logic.
/// This is the main trait: implement it to add your logic.

Technical Terminology Precision

Use precise terms for the code lifecycle and generics to maintain low cognitive load.

• Declaration (Header) vs. Definition (Body) vs. Usage (Call Site).
• Parameters (Slots) belong to the Header and Body.
• Arguments (Fillers) belong to the Call Site.

See Technical Terminology Precision for the complete mental model and table.

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:

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:

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 setup.

Structs - Noun Phrase

Start with "A/An [noun]..." describing what it is:

// From std:
/// A contiguous growable array type, written as `Vec<T>`, short for 'vector'.
pub struct Vec<T> { ... }

/// A UTF-8-encoded, growable string.
pub struct String { ... }

/// A mutual exclusion primitive useful for protecting shared data.
pub struct Mutex<T> { ... }

// Our style:
/// A thread-safe container for managing worker thread lifecycle.
pub struct ThreadSafeGlobalState<F> { ... }

/// An offscreen buffer for testing terminal rendering.
pub struct OffscreenBuffer { ... }

Enums - What It Represents

Start with "A/An [noun]..." or "The [type]...":

// From std:
/// An `Ordering` is the result of a comparison between two values.
pub enum Ordering { Less, Equal, Greater }

/// An IP address, either IPv4 or IPv6.
pub enum IpAddr { V4(...), V6(...) }

// Our style:
/// An indication of whether the worker thread is running or terminated.
pub enum LivenessState { Running, Terminated }

/// A decision about whether the worker thread should shut down.
pub enum ShutdownDecision { ContinueRunning, ShutdownNow }

Traits - "A trait for..."

// Our style:
/// A trait for creating the coupled [`Worker`] + [`Waker`] pair atomically.
pub trait RRTFactory { ... }

/// A trait for implementing the blocking I/O loop on the dedicated RRT thread.
pub trait RRTWorker { ... }

Methods & Functions - Third-Person Verb

Start with what the method/function does using third-person:

// From std:
/// Constructs a new, empty `Vec<T>`.
pub fn new() -> Vec<T> { ... }

/// Returns the number of elements in the vector.
pub fn len(&self) -> usize { ... }

/// Appends an element to the back of a collection.
pub fn push(&mut self, value: T) { ... }

/// Returns the contained `Some` value, consuming the `self` value.
pub fn unwrap(self) -> T { ... }

// Our style:
/// Creates new thread state with fresh liveness tracking.
pub fn new(waker: W) -> Self { ... }

/// Checks if the thread should self-terminate.
pub fn should_self_terminate(&self) -> ShutdownDecision { ... }

Associated Types - "The type of..." or "The type..."

Follow the Rust std convention (e.g., Iterator::Item, Future::Output):

// From std:
/// The type of the elements being iterated over.
type Item;

/// The type of value produced on completion.
type Output;

// Our style (user-provided types use "Your type"):
/// The type broadcast from your [`Worker`] to async subscribers.
type Event;

/// Your type implementing one iteration of the blocking I/O loop.
type Worker: RRTWorker<Event = Self::Event>;

/// Your type for interrupting the blocked dedicated RRT worker thread.
type Waker: RRTWaker;

Pattern: Use "The type [verb]..." or "Your concrete type [verb]..." where the verb describes what the type does:

• "The concrete type broadcast..." (Event - gets broadcast)
• "Your concrete type implementing..." (Worker - user provides this)
• "Your concrete type for..." (Waker - user provides this)

When to use "Your concrete type": For associated types that the user must provide - types with trait bounds like : RRTWorker. The word "concrete" emphasizes they provide an actual struct/enum, not just satisfy an abstract contract.

When to use "of": Only when describing what a type contains rather than what it is:

• std's Iterator::Item: "The type of the elements..." - Item contains elements
• std's Future::Output: "The type of value..." - Output contains a value

Parenthetical clarifiers: When context is needed, use parentheticals:

/// Your concrete type (that implements this method) is an injected dependency...

Gold standard: See RRTFactory in tui/src/core/resilient_reactor_thread/types.rs for a complete example of complex trait documentation with associated types.

Constants - Noun Phrase

/// Capacity of the broadcast channel for events.
pub const CHANNEL_CAPACITY: usize = 4_096;

/// ESC byte (1B in hex).
pub const ANSI_ESC: u8 = 27;

Note: All ANSI constants in tui/src/core/ansi/constants/ MUST follow the Standardized Doc Template. See [constant-conventions.md] for details.

Quick Reference Table

Module-Level Docs for Single-Type Files

When a file contains primarily one struct, enum, or trait, keep module docs minimal - just identify the file's purpose and link to the main type:

Single Type - Link to It

//! Thread-safe global state manager for the Resilient Reactor Thread pattern. See
//! [`ThreadSafeGlobalState`] for details.

Dedicated Test Files (PTY Tests)

For files dedicated to a single PTY integration test, use module-level documentation to describe the test's intent and provide execution instructions. This keeps the generate_pty_test! macro call clean.

Standard Pattern:

1. Summary: What the test validates.
2. Detailed Description/Protocol: Explaining the test logic and ANSI sequences.
3. Run with section: MUST be the last paragraph before link definitions, using an H1 header (# Run with:).

//! [`PTY`]-based integration test for [Feature Name].
//!
//! Validates that [specific behavior] works correctly in a real terminal environment.
//!
//! [Detailed description...]
//!
//! # Run with:
//!
//! ```bash
//! cargo test -p r3bl_tui --lib [test_name] -- --nocapture
//! ```
//!
//! [`PTY`]: https://en.wikipedia.org/wiki/Pseudoterminal

Why this matters:

• Immediately actionable: "Run with" instructions are at the top of the file.
• Clean implementation: Documentation is separated from the macro configuration.
• Docs.rs discovery: Module-level docs are the first thing users see when clicking the module on docs.rs.

Multiple Types - Bullet List

When a file contains multiple related types, use a brief intro + bullet list:

//! Core traits for the Resilient Reactor Thread (RRT) pattern.
//!
//! - [`RRTFactory`]: Creates coupled worker thread + waker
//! - [`RRTWorker`]: Work loop running on the thread
//! - [`RRTWaker`]: Interrupt a blocked thread
//!
//! See [module docs] for the full RRT pattern explanation.
//!
//! [module docs]: super

//! Thread liveness tracking for the Resilient Reactor Thread pattern. See
//! [`ThreadLiveness`], [`LivenessState`], and [`ShutdownDecision`].

Why minimal? The detailed documentation belongs on the types themselves (inverted pyramid). Module docs just help readers navigate to the right type. Don't duplicate content.

Follow-Up Sentences Need Explicit Subjects

After the opening line, subsequent sentences should use explicit subjects - don't start with verbs that leave the subject ambiguous:

❌ Bad: Abrupt Starts

/// A trait for interrupting blocked threads.
///
/// Called by `SubscriberGuard::drop()` to signal shutdown.

What's "called"? The trait? A method? The reader must guess.

✅ Good: Explicit Subjects

/// A trait for interrupting blocked threads.
///
/// [`SubscriberGuard::drop()`] calls [`wake_and_unblock_dedicated_thread()`] on implementors of this trait to signal
/// shutdown.

Now it's clear: the method is what's being called, on implementors of the trait.

Note: Traits themselves aren't "called" - methods are. Say what valid actions a trait can take: "This trait solves...", "This trait requires...", "This trait defines...". Don't say "This trait is called...".

Common Patterns to Fix

Method Doc Verb Tense

Methods should use third-person verbs (like Rust std docs), not imperative:

Why third-person? It reads naturally as "This method creates..." without needing to say "This method". Imperative form ("Create...") sounds like a command to the reader.

Self-Reference in Different Contexts

Section Headings for Reference Implementations

Use # Example (not # Concrete Implementation) when linking to reference implementations:

// ❌ Bad: Sounds like THE canonical implementation
/// # Concrete Implementation
///
/// See [`MioPollWorker`] for a concrete implementation.

// ✅ Good: Idiomatic Rust, implies there could be others
/// # Example
///
/// See [`MioPollWorker`] for an example implementation.

Why # Example?

• Matches Rust std lib conventions
• "example implementation" signals "one of potentially many"
• "concrete implementation" sounds like THE canonical choice

Part 1: Structure (Inverted Pyramid)

Heading Levels and Sidebar Navigation

The cargo doc static site only shows # (h1) and ## (h2) headings in the sidebar navigation. ### (h3) and below are not shown in the sidebar.

For sub-sections within a ## heading, use bold text (**bold**) instead of ###:

//! ## How It Works                     // ← Shown in sidebar
//!
//! **Creation and reuse** - ...        // ← NOT in sidebar, but visually distinct
//!
//! **Cooperative shutdown** - ...      // ← NOT in sidebar, but visually distinct

Why this matters: Using ### creates a false promise of navigability - readers expect to find it in the sidebar but can't. Bold text is visually similar but sets correct expectations.

Inverted Pyramid

Structure documentation with high-level concepts at the top, details below:

╲────────────╱
 ╲          ╱  High-level concepts - Module/trait/struct documentation
  ╲────────╱
   ╲      ╱  Mid-level details - Method group documentation
    ╲────╱
     ╲  ╱  Low-level specifics - Individual method documentation
      ╲╱

Avoid making readers hunt through method docs for the big picture.

Placement Guidelines

Reference Up, Not Down

/// See the [module-level documentation] for complete usage examples.
///
/// [module-level documentation]: mod@crate::example
pub fn some_method(&self) -> Result<()> { /* ... */ }

Part 2: Intra-doc Links

Golden Rules

1. Use crate:: paths (not super::) - absolute paths are stable
2. Use reference-style links - keep prose clean
3. Place all link definitions at bottom of comment block
4. Include () for functions/methods - distinguishes from types

Link Source Priority

When deciding local vs external links, follow this priority:

Key principle: If it's in Cargo.toml, use local links (validated, offline-capable, version-matched).

Link All Symbols for Refactoring Safety

Every codebase symbol in backticks must be a link. This isn't just style -it's safety.

When you rename, move, or delete a symbol:

• With links: cargo doc fails with a clear error pointing to the stale reference
• Without links: The docs silently rot, referencing symbols that no longer exist

Rule: If it's a symbol from your codebase and it's in backticks, make it a link.

// ❌ Bad: Will silently rot when Parser is renamed
/// Uses `Parser` for tokenization.

// ✅ Good: cargo doc will catch if Parser is renamed
/// Uses [`Parser`] for tokenization.
///
/// [`Parser`]: crate::Parser

Quick Reference

✅ Good: Reference-Style Links

/// This struct uses [`Position`] to track cursor location.
///
/// The [`render()`] method updates the display.
///
/// [`Position`]: crate::Position
/// [`render()`]: Self::render

❌ Bad: Inline Links

/// This struct uses [`Position`](crate::Position) to track cursor location.

❌ Bad: No Links

/// This struct uses `Position` to track cursor location.

Linking to Dependency Crates

For crates listed in your Cargo.toml dependencies, use direct intra-doc links instead of external hyperlinks to docs.rs. Rustdoc automatically resolves these when the dependency is built.

✅ Good: Direct Dependency Links

//! **UI freezes** on terminal resize when using [`tokio::io::stdin()`].
//! Internally, cancelling a [`tokio::select!`] branch doesn't stop the read.
//! However, the use of [Tokio's stdin] caused the first two issues.
//!
//! [`tokio::select!`]: tokio::select
//! [`tokio::io::stdin()`]: tokio::io::stdin
//! [Tokio's stdin]: tokio::io::stdin

/// Uses [`mio::Poll`] to efficiently wait on file descriptor events.
///
/// [`mio::Poll`]: mio::Poll

//! Use [`crossterm`]'s `enable_raw_mode` for terminal input.
//!
//! [`crossterm`]: ::crossterm

❌ Bad: External docs.rs Links for Dependencies

/// Uses [mio::Poll](https://docs.rs/mio/latest/mio/struct.Poll.html) to wait.

Don't use docs.rs URLs for crates that are already in your Cargo.toml.

Why direct links are better for dependencies:

• Clickable in local cargo doc output (works offline)
• Version-matched to your actual dependency version
• Validated by rustdoc (broken links caught at build time)
• Consistent style with internal crate links