Comments
Lexer
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_DOCIsolatedCR :
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 outer 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