Skip to content

Commit

Permalink
Merge pull request #1563 from chorman0773/spec-add-identifiers-comments
Browse files Browse the repository at this point in the history
Add spec identifiers to comments.md
  • Loading branch information
traviscross authored Sep 24, 2024
2 parents 58cb78f + cc29656 commit bad7ef1
Showing 1 changed file with 18 additions and 2 deletions.
20 changes: 18 additions & 2 deletions src/comments.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Comments

r[comments.syntax]

> **<sup>Lexer</sup>**\
> LINE_COMMENT :\
> &nbsp;&nbsp; &nbsp;&nbsp; `//` (~\[`/` `!` `\n`] | `//`) ~`\n`<sup>\*</sup>\
Expand Down Expand Up @@ -34,26 +36,40 @@
## Non-doc comments

r[comments.normal]

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

r[comments.normal.tokenization]
Non-doc comments are interpreted as a form of whitespace.

## Doc comments

r[comments.doc]

r[comments.doc.syntax]
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
special syntax for [`doc` attributes].

r[comments.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"]`. They must therefore
appear before something that accepts an outer attribute.

r[comments.doc.inner-syntax]
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
that follows.

r[comments.doc.inner-attributes]
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.

r[comments.doc.bare-crs]
The character `U+000D` (CR) is not allowed in doc comments.

> **Note**: It is conventional for doc comments to contain Markdown, as expected by
Expand Down

0 comments on commit bad7ef1

Please sign in to comment.