From d5bef01c915567fc958be379ebe4e038f59faf60 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 7 Aug 2024 22:14:26 -0400 Subject: [PATCH 1/3] Add identifiers to comments.md --- src/comments.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/src/comments.md b/src/comments.md index 795bf637c..753051f69 100644 --- a/src/comments.md +++ b/src/comments.md @@ -1,5 +1,8 @@ # Comments + +r[comments.lexical] + > **Lexer**\ > LINE_COMMENT :\ >       `//` (~\[`/` `!` `\n`] | `//`) ~`\n`\*\ @@ -34,25 +37,39 @@ ## 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.attribute] +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"]`. +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-attribute] +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-cr] The character `U+000D` (CR) is not allowed in doc comments. > **Note**: The sequence `U+000D` (CR) immediately followed by `U+000A` (LF) would have been previously transformed into a single `U+000A` (LF). From 9a2836efabf6d94536e615eff593422f99d53dae Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 21 Aug 2024 19:51:17 -0400 Subject: [PATCH 2/3] Remove double line break from comments.md --- src/comments.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/comments.md b/src/comments.md index 753051f69..9b7b6cde7 100644 --- a/src/comments.md +++ b/src/comments.md @@ -1,6 +1,5 @@ # Comments - r[comments.lexical] > **Lexer**\ From cc29656aadf65c45edb94b0c58cf4b2eabb3b988 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Tue, 24 Sep 2024 22:23:30 +0000 Subject: [PATCH 3/3] Add review changes --- src/comments.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/comments.md b/src/comments.md index 9b7b6cde7..fa72aba01 100644 --- a/src/comments.md +++ b/src/comments.md @@ -1,6 +1,6 @@ # Comments -r[comments.lexical] +r[comments.syntax] > **Lexer**\ > LINE_COMMENT :\ @@ -53,7 +53,7 @@ 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]. -r[comments.doc.attribute] +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"]`. @@ -63,12 +63,12 @@ Line comments beginning with `//!` and block comments `/*! ... */` are doc comments that apply to the parent of the comment, rather than the item that follows. -r[comments.doc.inner-attribute] +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-cr] +r[comments.doc.bare-crs] The character `U+000D` (CR) is not allowed in doc comments. > **Note**: The sequence `U+000D` (CR) immediately followed by `U+000A` (LF) would have been previously transformed into a single `U+000A` (LF).