Comments

Line comments begin with // and extend to the end of the line.

line_comment = "//" { any_char_except_newline } newline ;

Non-doc comments are discarded during lexical analysis and do not affect program semantics. Doc comments (§2.2:5) are surfaced onto the AST and do not affect runtime behaviour either, but their text is available to downstream tooling.

// This is a comment
fn main() -> i32 {
    42  // This is also a comment
}

Block comments (/* ... */) are not currently supported.

A line beginning with exactly three forward slashes (///) followed by any sequence of characters up to the end of the line introduces a doc comment. Four or more consecutive forward slashes (e.g. ////) are still ordinary line comments. The body of a doc comment is the text after the marker with at most one single leading space removed.

doc_line = "///" { any_char_except_newline } newline ;

A run of consecutive doc_lines, with no blank line and no non-doc token between them, forms a doc block. A blank line, a non-doc token, or end of file terminates the run.

A doc block qualifies as the module candidate iff it is the textually first doc block in the file and no item appears above it in the same file. A qualifying block separated by at least one blank line from the next item attaches to the module; a qualifying block glued to the next item (no blank line between) attaches to that item.

A doc block that does not qualify as the module candidate must be immediately followed (no blank line between) by an item; otherwise it is a parse error.

/// Module-level documentation.

/// Documentation attached to `main`.
fn main() -> i32 {
    42
}