Outer Documentation Comment

Outer documentation comments are specialized lexical constructs in Rust that document the programming construct immediately following them. Unlike standard code comments, they are parsed by the compiler and processed by the rustdoc tool to generate structured HTML documentation.

Rust supports two syntactic forms for outer documentation comments: line comments and block comments. Both forms natively support Markdown formatting.

Line Comments Line-based outer documentation comments are denoted by three forward slashes (///). They must be repeated for each line of the comment block.

/// Represents a point in 2D space.
/// 
/// Contains `x` and `y` coordinate values.
pub struct Point {
    /// The x-coordinate.
    pub x: f64,
    /// The y-coordinate.
    pub y: f64,
}

Block Comments Block-based outer documentation comments are denoted by /** to open the block and */ to close it.

/**
Represents a point in 3D space.

Contains `x`, `y`, and `z` coordinate values.
*/
pub struct Point3D {
    pub x: f64,
    pub y: f64,
    pub z: f64,
}

AST Desugaring At the Abstract Syntax Tree (AST) level, the Rust compiler desugars outer documentation comments into #[doc] attributes. The rustdoc generator operates on these attributes rather than the raw comment syntax.

The following outer comment:

/// Computes the square root.
pub fn sqrt(val: f64) -> f64 {
    unimplemented!()
}

Is syntactically and semantically equivalent to the following built-in compiler attribute:

#[doc = " Computes the square root."]
pub fn sqrt(val: f64) -> f64 {
    unimplemented!()
}

Placement and Parsing Rules Because outer documentation comments are treated as attributes applied to the subsequent construct, they must strictly precede a valid Rust item (such as a struct, enum, fn, trait, or mod), an associated item, a struct field, or an enum variant.

If an outer documentation comment is placed before an internal function statement (such as a let binding), rustdoc will not process it or generate HTML documentation. Instead, the compiler will emit an unused_doc_comments warning. Standard code comments (//) must be used to document internal statements.

If an outer documentation comment is placed in a location where there is no subsequent construct to attach to at all—such as at the end of a file or at the end of a block scope—the Rust compiler will emit error E0585, indicating a dangling documentation comment.

fn example_scope() {
    /// This triggers an `unused_doc_comments` warning because it precedes a statement.
    let _value = 42;
    
    /// This comment has no subsequent construct to attach to.
    /// The compiler will emit error E0585 (dangling documentation comment).
}

Master Rust with Deep Grasping Methodology!

Learn More