src/doc/reference/src/comments.md

   1 # Comments
   2
   3 > **<sup>Lexer</sup>**\
   4 > LINE_COMMENT :\
   5 > &nbsp;&nbsp; &nbsp;&nbsp; `//` (~\[`/` `!` `\n`] | `//`) ~`\n`<sup>\*</sup>\
   6 > &nbsp;&nbsp; | `//`
   7 >
   8 > BLOCK_COMMENT :\
   9 > &nbsp;&nbsp; &nbsp;&nbsp; `/*` (~\[`*` `!`] | `**` | _BlockCommentOrDoc_)
  10 >      (_BlockCommentOrDoc_ | ~`*/`)<sup>\*</sup> `*/`\
  11 > &nbsp;&nbsp; | `/**/`\
  12 > &nbsp;&nbsp; | `/***/`
  13 >
  14 > INNER_LINE_DOC :\
  15 > &nbsp;&nbsp; `//!` ~\[`\n` _IsolatedCR_]<sup>\*</sup>
  16 >
  17 > INNER_BLOCK_DOC :\
  18 > &nbsp;&nbsp; `/*!` ( _BlockCommentOrDoc_ | ~\[`*/` _IsolatedCR_] )<sup>\*</sup> `*/`
  19 >
  20 > OUTER_LINE_DOC :\
  21 > &nbsp;&nbsp; `///` (~`/` ~\[`\n` _IsolatedCR_]<sup>\*</sup>)<sup>?</sup>
  22 >
  23 > OUTER_BLOCK_DOC :\
  24 > &nbsp;&nbsp; `/**` (~`*` | _BlockCommentOrDoc_ )
  25 >              (_BlockCommentOrDoc_ | ~\[`*/` _IsolatedCR_])<sup>\*</sup> `*/`
  26 >
  27 > _BlockCommentOrDoc_ :\
  28 > &nbsp;&nbsp; &nbsp;&nbsp; BLOCK_COMMENT\
  29 > &nbsp;&nbsp; | OUTER_BLOCK_DOC\
  30 > &nbsp;&nbsp; | INNER_BLOCK_DOC
  31 >
  32 > _IsolatedCR_ :\
  33 > &nbsp;&nbsp; _A `\r` not followed by a `\n`_
  34
  35 ## Non-doc comments
  36
  37 Comments follow the general C++ style of line (`//`) and
  38 block (`/* ... */`) comment forms. Nested block comments are supported.
  39
  40 Non-doc comments are interpreted as a form of whitespace.
  41
  42 ## Doc comments
  43
  44 Line doc comments beginning with exactly _three_ slashes (`///`), and block
  45 doc comments (`/** ... */`), both outer doc comments, are interpreted as a
  46 special syntax for [`doc` attributes]. That is, they are equivalent to writing
  47 `#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into
  48 `#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`.
  49
  50 Line comments beginning with `//!` and block comments `/*! ... */` are
  51 doc comments that apply to the parent of the comment, rather than the item
  52 that follows.  That is, they are equivalent to writing `#![doc="..."]` around
  53 the body of the comment. `//!` comments are usually used to document
  54 modules that occupy a source file.
  55
  56 Isolated CRs (`\r`), i.e. not followed by LF (`\n`), are not allowed in doc
  57 comments.
  58
  59 ## Examples
  60
  61 ```rust
  62 //! A doc comment that applies to the implicit anonymous module of this crate
  63
  64 pub mod outer_module {
  65
  66     //!  - Inner line doc
  67     //!! - Still an inner line doc (but with a bang at the beginning)
  68
  69     /*!  - Inner block doc */
  70     /*!! - Still an inner block doc (but with a bang at the beginning) */
  71
  72     //   - Only a comment
  73     ///  - Outer line doc (exactly 3 slashes)
  74     //// - Only a comment
  75
  76     /*   - Only a comment */
  77     /**  - Outer block doc (exactly) 2 asterisks */
  78     /*** - Only a comment */
  79
  80     pub mod inner_module {}
  81
  82     pub mod nested_comments {
  83         /* In Rust /* we can /* nest comments */ */ */
  84
  85         // All three types of block comments can contain or be nested inside
  86         // any other type:
  87
  88         /*   /* */  /** */  /*! */  */
  89         /*!  /* */  /** */  /*! */  */
  90         /**  /* */  /** */  /*! */  */
  91         pub mod dummy_item {}
  92     }
  93
  94     pub mod degenerate_cases {
  95         // empty inner line doc
  96         //!
  97
  98         // empty inner block doc
  99         /*!*/
 100
 101         // empty line comment
 102         //
 103
 104         // empty outer line doc
 105         ///
 106
 107         // empty block comment
 108         /**/
 109
 110         pub mod dummy_item {}
 111
 112         // empty 2-asterisk block isn't a doc block, it is a block comment
 113         /***/
 114
 115     }
 116
 117     /* The next one isn't allowed because outer doc comments
 118        require an item that will receive the doc */
 119
 120     /// Where is my item?
 121 #   mod boo {}
 122 }
 123 ```
 124
 125 [`doc` attributes]: ../rustdoc/the-doc-attribute.html