Writing Good Rust Documentation

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

1. Structure - Inverted pyramid principle
2. Links - Intra-doc link patterns
3. Constants - Human-readable numeric literals
4. 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

Part 1: Structure (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 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.

For detailed patterns, see link-patterns.md in this skill.

Part 3: Constant Conventions

Use human-readable numeric literals for byte constants:

✅ Good: Human-Readable

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

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

/// Mask to convert control character to lowercase (0x60 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

Verify Documentation Builds

cargo doc --no-deps
cargo test --doc

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;

// For platform-specific test modules:
#[cfg(all(any(test, doc), target_os = "linux"))]
pub mod linux_only_tests;

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

Checklist

Before committing documentation:

• High-level concepts at module/trait level (inverted pyramid)
• All links use reference-style with crate:: paths
• All link definitions at bottom of comment blocks
• Constants use binary/byte literal/decimal (not hex)
• Hex shown in comments for cross-reference
• Markdown tables formatted (cargo rustdoc-fmt)
• No broken links (cargo doc --no-deps)
• All code examples compile (cargo test --doc)

Supporting Files

Related Commands

Related Skills

• check-code-quality - Includes doc verification step
• organize-modules - Re-export chains, conditional visibility for doc links
• run-clippy - May suggest doc improvements