注释

^词法
行注释 :
      // (~[/ ! \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 {}
}
}