Markdown in Documentation

rustdoc parses all /// and //! documentation comments as CommonMark Markdown with GitHub Flavored Markdown (GFM) extensions—supporting headings, tables, task lists, strikethrough, footnotes, blockquotes, and fenced code blocks.

/// First paragraph = Short Summary shown in module overview tables.
///
/// Detailed explanation with **bold**, *italics*, and `inline_code`.
///
/// # Examples
/// ```
/// assert_eq!(1 + 1, 2);
/// ```

Standard Section Headings in Rust API Docs

By convention across the standard library and ecosystem, item-level documentation uses level-1 Markdown headings (# Heading) for standardized sections in the following order:

Conventional Heading	When to Include	Purpose
`# Examples`	Almost every public item	Shows one or more runnable code snippets demonstrating typical usage.
`# Panics`	Functions that can panic	Lists the exact inputs or states that cause the function to panic.
`# Errors`	Functions returning `Result<T, E>`	Describes the conditions under which each `Err` variant is returned.
`# Safety`	`unsafe fn` and `unsafe trait`	Lists the invariants the caller or implementer must uphold to avoid UB.
`# Aborts`	Functions that can call `process::abort`	Documents conditions that terminate the process immediately.
`# Time Complexity`	Collection / algorithm methods	Documents asymptotic runtime and memory bounds (e.g., $O(1)$ amortized).

Using Tables, Lists, and Alert Callouts in Doc Comments

GFM tables and warning blockquotes clarify behavioral matrices directly inside IDE hover tooltips and cargo doc pages:

/// Formats a byte count using binary (`KiB`, `MiB`) or decimal (`kB`, `MB`) units.
///
/// | Mode | Base | `1024` Bytes Output | `1_000_000` Bytes Output |
/// | :--- | :--- | :--- | :--- |
/// | `Binary` | $1024$ ($2^{10}$) | `"1.0 KiB"` | `"976.6 KiB"` |
/// | `Decimal` | $1000$ ($10^3$) | `"1.0 kB"` | `"1.0 MB"` |
///
/// > **Note:** Values smaller than 1 unit are formatted as raw byte counts (`"512 B"`).
///
/// # Examples
///
/// ```
/// assert_eq!(format_kib(2048), "2.0 KiB");
/// ```
pub fn format_kib(bytes: u64) -> String {
    if bytes < 1024 {
        format!("{bytes} B")
    } else {
        format!("{:.1} KiB", (bytes as f64) / 1024.0)
    }
}

fn main() {
    println!("512 -> {}", format_kib(512));
    println!("2048 -> {}", format_kib(2048));
}

512 -> 512 B
2048 -> 2.0 KiB

Preventing Indented Text from Becoming a Code Block

In CommonMark, indenting a paragraph by 4 or more spaces after /// turns that paragraph into an untagged Rust code block, which cargo test --doc will attempt to compile as Rust code! Always use triple-backtick fenced blocks (```rust or ```text) rather than 4-space indentation for code or ASCII diagrams inside doc comments.