注释
词法
行注释 :
//
(~[/
!
\n
] |//
) ~\n
*
|//
块注释 :
/*
(~[*
!
] |**
| 块注释或文档) (块注释或文档 | ~*/
)**/
|/**/
|/***/
内部行文档 :
//!
~[\n
孤立CR]*内部块文档 :
/*!
( 块注释或文档 | ~[*/
孤立CR] )**/
外部行文档 :
///
(~/
~[\n
孤立CR]*)?外部块文档 :
/**
(~*
| 块注释或文档 ) (块注释或文档 | ~[*/
孤立CR])**/
块注释或文档 :
块注释
| 外部块文档
| 内部块文档孤立CR :
\r
不紧随\n
非文档注释
注释遵循 C++ 风格的行 (//
) 和块 (/* ... */
) 注释的一般形式。支持嵌套的块注释。
非文档注释被解释为空白的一种形式。
文档注释
以三个斜线开始的行文档注释 (///
),以及块文档注释 (/** ... */
),都是内部文档注释,被解释为 doc
属性 的特殊语法。
相当于在注释主体的周围写上 #[doc="..."]
,即 /// Foo
和 /** Bar */
会转换成 #[doc="Bar"]
。
以 //!
开头的行注释和 /*! ... */
块注释也是文档注释,其应用于父级,而不是之后条目。
相当于在注释位置写上 #![doc="..."]
。 //!
注释通常用于拥有源文件的模块。
在文档注释中不允许孤立的 CR (\r
) ,即后面没有 LF (\n
) 。
示例
#![allow(unused)] fn main() { //! 应用于这个 crate 隐式匿名模块的文档注释 pub mod outer_module { //! - 内部行文档 //!! - 仍是内部行文档 (但开始有感叹号) /*! - 内部块文档 */ /*!! - 仍是内部块文档 (但开始有感叹号) */ // - 仅是注释 /// - 外部行文档 (正好 3 斜线) //// - 仅是注释 /* - 仅是注释 */ /** - 外部块文档 (正好 2 星号) */ /*** - 仅是注释 */ pub mod inner_module {} pub mod nested_comments { /* 在 Rust /* 可以 /* 嵌套注释 */ */ */ // 所有三种类型的块注释都可以包含或嵌套任何其他类型的注释: /* /* */ /** */ /*! */ */ /*! /* */ /** */ /*! */ */ /** /* */ /** */ /*! */ */ pub mod dummy_item {} } pub mod degenerate_cases { // 空内部行文档 //! // 空内部块文档 /*!*/ // 空行注释 // // 空外部行文档 /// // 空块注释 /**/ pub mod dummy_item {} // 空的 2 星号块不是块文档,而是块注释。 /***/ } /* 下一个是不允许的, 外部文档注释需要一个条目来接收文档 */ /// 我的条目在哪里? mod boo {} } }