> ## 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 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.
```rust theme={"dark"}
/// 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.
```rust theme={"dark"}
/**
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:
```rust theme={"dark"}
/// Computes the square root.
pub fn sqrt(val: f64) -> f64 {
unimplemented!()
}
```
Is syntactically and semantically equivalent to the following built-in compiler attribute:
```rust theme={"dark"}
#[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.
```rust,compile_fail theme={"dark"}
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).
}
```
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
