注释
Lexer
COMMENT →
LINE_COMMENT
| INNER_LINE_DOC
| OUTER_LINE_DOC
| INNER_BLOCK_DOC
| OUTER_BLOCK_DOC
| BLOCK_COMMENT
LINE_COMMENT →
// ( ~[/ ! LF] | // ) ~LF*
| // EOF
| //immediately followed by LF
BLOCK_COMMENT →
/* ^
( BLOCK_COMMENT_OR_DOC | ( !*/ CHAR ) )*
*/
INNER_LINE_DOC →
//! ^ LINE_DOC_COMMENT_CONTENT ( LF | EOF )
LINE_DOC_COMMENT_CONTENT → ( !CR ~LF )*
INNER_BLOCK_DOC →
/*! ^ ( BLOCK_COMMENT_OR_DOC | BLOCK_CHAR )* */
OUTER_LINE_DOC →
/// ^ LINE_DOC_COMMENT_CONTENT ( LF | EOF )
OUTER_BLOCK_DOC →
/** ![* /]
^
( ~* | BLOCK_COMMENT_OR_DOC )
( BLOCK_COMMENT_OR_DOC | BLOCK_CHAR )*
*/
BLOCK_CHAR → ( !( */ | CR ) CHAR )
BLOCK_COMMENT_OR_DOC →
INNER_BLOCK_DOC
| OUTER_BLOCK_DOC
| BLOCK_COMMENT
非文档注释
注释遵循一般的 C++ 风格的行注释（//）和块注释（/* ... */）形式。支持嵌套块注释。
非文档注释被解释为一种空白形式。
文档注释
以恰好三个斜杠（///）开头的行文档注释和块文档注释（/** ... */），都是外部文档注释，被解释为 doc 属性的特殊语法。
也就是说，它们等同于在注释主体周围编写 #[doc="..."]，即 /// Foo 变成 #[doc=" Foo"]，/** Bar */ 变成 #[doc=" Bar "]。因此，它们必须出现在接受外部属性的内容之前。
以 //! 开头的行注释和 /*! ... */ 块注释是应用于注释父级而不是后续项的文档注释。
也就是说，它们等同于在注释主体周围编写 #![doc="..."]。//! 注释通常用于记录占据源文件的模块。
字符 U+000D (CR) 不允许在文档注释中使用。
Note
按照惯例，文档注释包含 Markdown，正如
rustdoc所期望的那样。但是，注释语法不尊重任何内部 Markdown。/** `glob = "*/*.rs";` */在第一个*/处终止注释，剩余的代码会导致语法错误。这与行文档注释相比，稍微限制了块文档注释的内容。
Note
序列
U+000D(CR) 紧接着U+000A(LF) 之前已被转换为单个U+000A(LF)。
示例
#![allow(unused)]
fn main() {
//! A doc comment that applies to the implicit anonymous module of this crate
pub mod outer_module {
//! - Inner line doc
//!! - Still an inner line doc (but with a bang at the beginning)
/*! - Inner block doc */
/*!! - Still an inner block doc (but with a bang at the beginning) */
// - Only a comment
/// - Outer line doc (exactly 3 slashes)
//// - Only a comment
/* - Only a comment */
/** - Outer block doc (exactly) 2 asterisks */
/*** - Only a comment */
pub mod inner_module {}
pub mod nested_comments {
/* In Rust /* we can /* nest comments */ */ */
// All three types of block comments can contain or be nested inside
// any other type:
/* /* */ /** */ /*! */ */
/*! /* */ /** */ /*! */ */
/** /* */ /** */ /*! */ */
pub mod dummy_item {}
}
pub mod degenerate_cases {
// empty inner line doc
//!
// empty inner block doc
/*!*/
// empty line comment
//
// empty outer line doc
///
// empty block comment
/**/
pub mod dummy_item {}
// empty 2-asterisk block isn't a doc block, it is a block comment
/***/
}
/* The next one isn't allowed because outer doc comments
require an item that will receive the doc */
/// Where is my item?
mod boo {}
}
}