> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rust 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.
```rust theme={"dark"}
//! 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.
```rust theme={"dark"}
/*!
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 = "..."]`.
```rust theme={"dark"}
// 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.
```rust theme={"dark"}
//! 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;
}
}
```
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
