注释

词法分析器

LINE_COMMENT

      // (~[/ ! \n] | //) ~\n*

   | //

BLOCK_COMMENT

      /* (~[* !] | ** | BlockCommentOrDoc) (BlockCommentOrDoc | ~*/)* */

   | /**/

   | /***/

INNER_LINE_DOC

   //! ~[\n IsolatedCR]*

INNER_BLOCK_DOC

   /*! ( BlockCommentOrDoc | ~[*/ IsolatedCR] )* */

OUTER_LINE_DOC

   /// (~/ ~[\n IsolatedCR]*)?

OUTER_BLOCK_DOC

   /** (~* | BlockCommentOrDoc ) (BlockCommentOrDoc | ~[*/ IsolatedCR])* */

BlockCommentOrDoc :

      BLOCK_COMMENT

   | OUTER_BLOCK_DOC

   | INNER_BLOCK_DOC

IsolatedCR :

   \r

非文档注释

注释遵循 C++ 风格的通用行注释 (//) 和块注释 (/* ... */) 形式。支持嵌套块注释。

非文档注释被解释为一种空白符形式。

文档注释

以正好_三个_斜杠 (///) 开头的行文档注释和块文档注释 (/** ... */) 都是外部文档注释，它们被解释为 doc 属性 的特殊语法。也就是说，它们等效于在注释主体周围编写 #[doc="..."]，例如，/// Foo 变为 #[doc="Foo"]，而 /** Bar */ 变为 #[doc="Bar"]。

以 //! 开头的行注释和 /*! ... */ 块注释是应用于注释父级而不是后面项目的文档注释。也就是说，它们等效于在注释主体周围编写 #![doc="..."]。//! 注释通常用于记录占据源文件的模块。

字符 U+000D (CR) 不允许出现在文档注释中。

**注意**：序列 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 {}
}
}