Inner Documentation Comment

Inner documentation comments in Rust are annotations used to document the enclosing item that contains the comment itself, rather than the item immediately following it. They are parsed by the rustdoc tool to generate HTML documentation for any item that contains a block, such as the root scope of a crate, a module, a function body, or a method.

Syntax

Rust supports two syntactic forms for inner documentation comments: line comments and block comments.

Line Comments Line comments begin with //! and continue to the end of the line. Multiple consecutive //! lines are concatenated into a single documentation block.

//! This is an inner line documentation comment.
//! It documents the enclosing item it resides in.

Block Comments Block comments begin with /*! and end with */. They can span multiple lines and contain internal formatting.

/*!
This is an inner block documentation comment.
It can span multiple lines.
*/

Compiler Desugaring

At the Abstract Syntax Tree (AST) level, the Rust compiler desugars inner documentation comments into inner doc attributes. Specifically, //! and /*! ... */ are translated into #![doc = "..."].

// The following inner comment:
//! Enclosing item documentation.

// Is strictly equivalent to the following inner attribute:
#![doc = " Enclosing item documentation."]

Because they desugar to inner attributes (denoted by the ! in #![...]), they apply to the AST node they are inside, not the node they precede.

Placement and Parsing Rules

Inner documentation comments are subject to strict placement rules within the Rust module system and block structures:

1. Scope: They must be placed at the top of the enclosing scope. This can be at the very beginning of a file (like main.rs or lib.rs), or immediately after the opening brace ({) of a block-containing item (like mod { ... }, fn { ... }, or impl { ... }).
2. Ordering: They must appear before any declarations, statements, or items within that scope. Placing an inner documentation comment after an item or statement will cause rustc to intercept the misplaced comment and emit the compiler error expected outer doc comment.
3. Markdown Support: The text within the comment is parsed as CommonMark Markdown by rustdoc, supporting standard Markdown elements like headings, code blocks, and links.

//! This comment is valid because it is at the top of the file/module.

use std::collections::HashMap;

// //! This comment would cause an `expected outer doc comment` compiler error 
// //! if uncommented, because it appears after the `use` statement.

pub mod example_module {
    //! This inner comment is valid because it is at the top of the module block.
    
    pub fn do_work() {
        //! This inner comment is also valid because it is at the top of the function block.
        //! It documents the `do_work` function.
        
        let _x = 42;
    }
}

Master Rust with Deep Grasping Methodology!

Learn More