Comments

^Lexer
LINE_COMMENT :
// (~[/ !] | //) ~\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 :
A \r not followed by a \n

Non-doc comments

Comments follow the general C++ style of line (//) and block (/* ... */) comment forms. Nested block comments are supported.

Non-doc comments are interpreted as a form of whitespace.

Doc comments

Line doc comments beginning with exactly three slashes (///), and block doc comments (/** ... */), both inner doc comments, are interpreted as a special syntax for doc attributes. That is, they are equivalent to writing #[doc="..."] around the body of the comment, i.e., /// Foo turns into #[doc="Foo"] and /** Bar */ turns into #[doc="Bar"].

Line comments beginning with //! and block comments /*! ... */ are doc comments that apply to the parent of the comment, rather than the item that follows. That is, they are equivalent to writing #![doc="..."] around the body of the comment. //! comments are usually used to document modules that occupy a source file.

Isolated CRs (\r), i.e. not followed by LF (\n), are not allowed in doc comments.

Examples

#![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 {}
}
}