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

✅ OK: External docs.rs Links for Non-Dependencies

For crates that are not in your Cargo.toml, external links are fine:

/// This is similar to how [rayon](https://docs.rs/rayon) handles parallel iteration.

Since rayon isn't a dependency, there's no local documentation to link to.

✅ OK: External Links for OS/CS/Hardware Terminology

For operating system concepts, computer science terminology, or hardware references that aren't Rust crates, use external URLs (man pages, Wikipedia, specs):

//! Uses [`epoll`] for efficient I/O multiplexing on Linux.
//! Implements the [`Actor`] pattern for message passing.
//! Reads from [`stdin`] which is a [`file descriptor`].
//!
//! [`epoll`]: https://man7.org/linux/man-pages/man7/epoll.7.html
//! [`Actor`]: https://en.wikipedia.org/wiki/Actor_model
//! [`stdin`]: std::io::stdin
//! [`file descriptor`]: https://man7.org/linux/man-pages/man2/open.2.html

Common external link targets:

Key distinction:

• mio (Rust crate in Cargo.toml) → [mio]: mio (local)
• epoll (Linux kernel API) → [epoll]: https://man7.org/... (external)

Pedagogical Links for Inclusivity

Link domain-specific terminology to external references (typically Wikipedia) even when the concept seems "obvious." This makes documentation accessible to readers of all backgrounds - not everyone comes from a CS degree or has the same experience level.

Rule: If a term has a formal definition that would help a newcomer understand the docs, link it. The cost of an extra link is near zero; the cost of excluding a reader is high.

// ✅ Good: Links pedagogical terms for inclusivity
//! This [design pattern] avoids all of this and allows async code to...
//! Resources are cleaned up via [`RAII`] when the guard is dropped.
//!
//! [design pattern]: https://en.wikipedia.org/wiki/Software_design_pattern
//! [`RAII`]: https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization

// ❌ Bad: Assumes reader already knows these terms
//! This design pattern avoids all of this and allows async code to...
//! Resources are cleaned up via RAII when the guard is dropped.

Common pedagogical link targets:

Note: The link source priority is also documented in link-patterns.md. This redundancy is intentional -SKILL.md content is loaded when the skill triggers, ensuring reliable application during doc generation. Supporting files require explicit reads and serve as detailed reference.

Part 3: Constant Conventions

Use human-readable numeric literals for byte constants:

✅ Good: Human-Readable

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

/// CSI bracket byte: `[` (91 decimal, 5B hex).
pub const ANSI_CSI_BRACKET: u8 = b'[';

/// Mask to convert control character to lowercase (60 in hex).
pub const CTRL_TO_LOWERCASE_MASK: u8 = 0b0110_0000;

❌ Bad: Hex Everywhere

pub const ANSI_ESC: u8 = 0x1B;
pub const ANSI_CSI_BRACKET: u8 = 0x5B;
pub const CTRL_TO_LOWERCASE_MASK: u8 = 0x60;

For detailed conventions, see constant-conventions.md in this skill.

Part 4: Formatting

Run cargo rustdoc-fmt

# Format specific file
cargo rustdoc-fmt path/to/file.rs

# Format all git-changed files
cargo rustdoc-fmt

# Format entire workspace
cargo rustdoc-fmt --workspace

What it does:

• Formats markdown tables with proper column alignment
• Converts inline links to reference-style
• Preserves code examples

If not installed:

cd build-infra && cargo install --path . --force

Markdown Table Alignment

Always use left-aligned columns in markdown tables. This is the default and most readable alignment for technical documentation.

Alignment Syntax

| Left-aligned | Left-aligned | Left-aligned |
| :----------- | :----------- | :----------- |
| data         | data         | data         |

The : on the left side of the dashes indicates left alignment. While the : is optional for left alignment (it's the default), always include it explicitly for consistency.

✅ Good: Left-Aligned (Default)

| Item Type | Pattern | Example |
| :-------- | :------ | :------ |
| Struct    | `A/An`  | `A thread-safe container...` |
| Trait     | `A trait for` | `A trait for creating...` |

Renders as:

❌ Avoid: Center or Right Alignment

| Item Type | Pattern | Example |
| :-------: | ------: | :-----: |
| Struct    | `A/An`  | `A thread-safe container...` |

Center (:---:) and right (---:) alignment are harder to scan and rarely appropriate for technical docs. Use them only when the content semantically requires it (e.g., numeric columns that should right-align for decimal alignment).

Why Left-Align?

• Scannability - Eyes naturally start at the left margin
• Consistency - All tables look the same throughout the codebase
• Prose readability - Technical descriptions flow better left-to-right
• Code snippets - Backtick content is easier to read left-aligned

No $ or LaTeX Math Delimiters

Do NOT use $ or $$ or \(...\) LaTeX math delimiters in rustdoc comments or chat responses. They do not render in the user's UI or standard markdown viewers. Use standard Markdown text, backticks (e.g., [start, start+len)), or code blocks instead.

Verify Documentation Builds

./check.fish --quick-doc
# (runs: cargo doc --no-deps, directly to serving dir; fastest for iteration)
# Use --doc for final verification before commits (includes staging/sync)

./check.fish --test
# (runs: cargo test --doc)

[!TIP] Run in a Subagent: Building workspace documentation and running doctests can take 1 to 2+ minutes. Delegate these commands to a background subagent (self) so the active conversation with the user is not blocked.

Code Examples in Docs

Golden Rule: Don't use ignore unless absolutely necessary.

Linking to Test Modules and Functions

/// See [`test_example`] for actual usage.
///
/// [`test_example`]: crate::tests::test_example

Make test module visible to docs:

#[cfg(any(test, doc))]
pub mod tests;

Platform-Specific Test Modules

When you see this warning:

"unresolved link to crate::path::test_module"

And the module is #[cfg(test)] only

Don't give up on links - Add conditional visibility instead of using plain text:

// Before (links won't resolve):
#[cfg(test)]
mod backend_tests;

// After (links resolve in docs):
#[cfg(any(test, doc))]
pub mod backend_tests;

Cross-Platform Docs for Platform-Specific Code

For code that only runs on specific platforms (e.g., Linux) but should have docs generated on all platforms (so developers on macOS can read them locally):

// ❌ Broken: Docs won't generate on macOS!
#[cfg(all(target_os = "linux", any(test, doc)))]
pub mod linux_only_module;

// ✅ Fixed: Docs generate on all platforms, tests run only on Linux
#[cfg(any(doc, all(target_os = "linux", test)))]
pub mod linux_only_module;
#[cfg(all(target_os = "linux", not(any(test, doc))))]
mod linux_only_module;

// Re-exports also need the doc condition
#[cfg(any(target_os = "linux", doc))]
pub use linux_only_module::*;

Key insight: The doc cfg flag doesn't override other conditions -it's just another flag. Use any(doc, ...) to make documentation an alternative path, not an additional requirement:

Apply at all levels - If linking to a nested module, both parent and child modules need the visibility change. See organize-modules skill for complete patterns and examples.

⚠️ Unix Dependency Caveat

The cfg(any(doc, ...)) pattern assumes the module's code compiles on all platforms. When the module uses Unix-only APIs (e.g., mio::unix::SourceFd, signal_hook, std::os::fd::AsRawFd), use cfg(any(all(unix, doc), ...)) instead to restrict doc builds to Unix platforms where the dependencies exist.

Three-tier platform hierarchy for cfg doc patterns:

Example - Unix-restricted doc build:

// Module uses mio::unix::SourceFd, signal_hook - Unix-only APIs.
// Dependencies in Cargo.toml are gated with cfg(unix).
// Doc builds are restricted to Unix where the dependencies exist.
#[cfg(any(all(unix, doc), all(target_os = "linux", test)))]
pub mod input;
#[cfg(all(target_os = "linux", not(any(test, doc))))]
mod input;

// Re-export also needs the unix-gated doc condition
#[cfg(any(target_os = "linux", all(unix, doc)))]
pub use input::*;

Rule of thumb: Match your doc cfg guard to your dependency's cfg guard. If the dep uses cfg(unix), gate docs with all(unix, doc). If the dep uses cfg(target_os = "linux"), gate docs with all(target_os = "linux", doc).

Cross-Platform Doctests with Platform-Specific APIs

When writing doctests (or doc code examples) that reference platform-specific APIs (such as Linux-only DirectToAnsiInputDevice or MioPollWorker), never downgrade the code example to a generic mock or use ```ignore. Real types provide concrete value and clickable intra-doc links for readers.

However, cargo test --doc executes across multiple operating systems (Linux, macOS, Windows). If a doctest references Linux-only symbols at the root level, it will fail to compile on Windows and macOS with unresolved import errors.

The linux_only Module Wrapper Pattern

To allow the doctest to showcase real Linux production types on Linux while cleanly passing on non-Linux platforms (Windows and macOS), wrap the Linux-specific code in a hidden module and conditionally re-export main:

/// ```no_run
/// # #[cfg(not(target_os = "linux"))]
/// # fn main() {}
/// # #[cfg(target_os = "linux")]
/// # use linux_only::main;
/// # #[cfg(target_os = "linux")]
/// # mod linux_only {
/// use r3bl_tui::{MioPollWorker, ok};
/// use r3bl_tui::core::resilient_reactor_thread::RRT;
///
/// // Global resources (static + const fn = singleton).
/// static SINGLETON: RRT<MioPollWorker> = RRT::new();
///
/// pub fn main() -> miette::Res

…(truncated)