From 586e6301f7c4f03e0fba0eb575b34befc28f0e78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Br=C3=A1ulio=20Bezerra?= Date: Thu, 20 Jul 2017 14:45:15 -0300 Subject: [PATCH 1/5] Added grammar of comments --- src/comments.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/comments.md b/src/comments.md index 784e19aff..1cd99102e 100644 --- a/src/comments.md +++ b/src/comments.md @@ -1,5 +1,24 @@ # Comments +> **Lexer** +> LINE_COMMENT : +>    `//` ~[\n\r]* +> +> BLOCK_COMMENT : +>    `/*` (BLOCK_COMMENT | .)* `*/` +> +> OUTER_DOC_LINE_COMMENT : +>    `//!` ~[\n\r]* +> +> OUTER_DOC_BLOCK_COMMENT : +>    `/*!` (OUTER_DOC_BLOCK_COMMENT | .)* `*/` +> +> INNER_DOC_LINE_COMMENT : +>    `///` ~[\n\r]* +> +> INNER_DOC_BLOCK_COMMENT : +>    `/**` (INNER_DOC_BLOCK_COMMENT | .)* `*/` + Comments in Rust code follow the general C++ style of line (`//`) and block (`/* ... */`) comment forms. Nested block comments are supported. From b27225969df0d0c3f02014ab66dba7b9cc1f041c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Br=C3=A1ulio=20Bezerra?= Date: Fri, 21 Jul 2017 01:49:31 -0300 Subject: [PATCH 2/5] Adjusted comments' grammar to account for special cases --- src/comments.md | 108 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 93 insertions(+), 15 deletions(-) diff --git a/src/comments.md b/src/comments.md index 1cd99102e..a4b13c083 100644 --- a/src/comments.md +++ b/src/comments.md @@ -2,31 +2,47 @@ > **Lexer** > LINE_COMMENT : ->    `//` ~[\n\r]* +>       `//` (~[`/` `!`] | `//`) ~`\n`\* +>    | `//` > > BLOCK_COMMENT : ->    `/*` (BLOCK_COMMENT | .)* `*/` +>       `/*` (~[`*` `!`] | `**` | _BlockCommentOrDoc_) +> (_BlockCommentOrDoc_ | ~`*/`)\* `*/` +>    | `/**/` +>    | `/***/` > -> OUTER_DOC_LINE_COMMENT : ->    `//!` ~[\n\r]* +> OUTER_LINE_DOC : +>    `//!` ~`\n`\* > -> OUTER_DOC_BLOCK_COMMENT : ->    `/*!` (OUTER_DOC_BLOCK_COMMENT | .)* `*/` +> OUTER_BLOCK_DOC : +>    `/*!` (_BlockCommentOrDoc_ | ~`*/`)\* `*/` > -> INNER_DOC_LINE_COMMENT : ->    `///` ~[\n\r]* +> INNER_DOC_LINE : +>    `///` (~`/` ~`\n`\*)? > -> INNER_DOC_BLOCK_COMMENT : ->    `/**` (INNER_DOC_BLOCK_COMMENT | .)* `*/` +> INNER_DOC_BLOCK : +>    `/**` (~`*` | _BlockCommentOrDoc_ ) +> (_BlockCommentOrDoc_ | ~`*/`)\* `*/` +> +> _BlockCommentOrDoc_ : +>       BLOCK_COMMENT +>    | OUTER_BLOCK_DOC +>    | INNER_BLOCK_DOC + +## Non-doc comments Comments in Rust code follow the general C++ style of line (`//`) and block (`/* ... */`) comment forms. Nested block comments are supported. -Line comments beginning with exactly _three_ slashes (`///`), and block -comments (`/** ... */`), are interpreted as a special syntax for `doc` -[attributes]. That is, they are equivalent to writing +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"]`. +`#[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 @@ -34,6 +50,68 @@ 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. -Non-doc comments are interpreted as a form of whitespace. +## Examples + +```rust +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 dummy_item {} +} +``` [attributes]: attributes.html From c623f98df96d949d7d40cb5c7eaac1b9c28a498b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Br=C3=A1ulio=20Bezerra?= Date: Fri, 21 Jul 2017 02:18:41 -0300 Subject: [PATCH 3/5] Corrected the INNER_{LINE|BLOCK}_DOC tokens' names to keep them coherent --- src/comments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/comments.md b/src/comments.md index a4b13c083..22b3582f2 100644 --- a/src/comments.md +++ b/src/comments.md @@ -17,10 +17,10 @@ > OUTER_BLOCK_DOC : >    `/*!` (_BlockCommentOrDoc_ | ~`*/`)\* `*/` > -> INNER_DOC_LINE : +> INNER_LINE_DOC : >    `///` (~`/` ~`\n`\*)? > -> INNER_DOC_BLOCK : +> INNER_BLOCK_DOC : >    `/**` (~`*` | _BlockCommentOrDoc_ ) > (_BlockCommentOrDoc_ | ~`*/`)\* `*/` > From d562d9d757ebb381e93c1a14f7dd6bdc14cd2ffa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Br=C3=A1ulio=20Bezerra?= Date: Mon, 24 Jul 2017 16:15:14 -0300 Subject: [PATCH 4/5] Added example of top-level doc comment --- src/comments.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/comments.md b/src/comments.md index 22b3582f2..898ad3aeb 100644 --- a/src/comments.md +++ b/src/comments.md @@ -53,6 +53,8 @@ modules that occupy a source file. ## Examples ```rust +//! A doc comment that applies to the implicit anonymous module of this crate + pub mod outer_module { //! - Inner line doc @@ -110,7 +112,7 @@ pub mod outer_module { require an item that will receive the doc */ /// Where is my item? -# mod dummy_item {} +# mod boo {} } ``` From cd80d1fcf69a65800829f0911e6d25e6f9a849cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Br=C3=A1ulio=20Bezerra?= Date: Mon, 7 Aug 2017 10:04:12 -0300 Subject: [PATCH 5/5] Isolated CRs are not allowed in doc comments --- src/comments.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/comments.md b/src/comments.md index 898ad3aeb..b855f6f0e 100644 --- a/src/comments.md +++ b/src/comments.md @@ -12,22 +12,25 @@ >    | `/***/` > > OUTER_LINE_DOC : ->    `//!` ~`\n`\* +>    `//!` ~[`\n` _IsolatedCR_]\* > > OUTER_BLOCK_DOC : ->    `/*!` (_BlockCommentOrDoc_ | ~`*/`)\* `*/` +>    `/*!` ( _BlockCommentOrDoc_ | ~[`*/` _IsolatedCR_] )\* `*/` > > INNER_LINE_DOC : ->    `///` (~`/` ~`\n`\*)? +>    `///` (~`/` ~[`\n` _IsolatedCR_]\*)? > > INNER_BLOCK_DOC : >    `/**` (~`*` | _BlockCommentOrDoc_ ) -> (_BlockCommentOrDoc_ | ~`*/`)\* `*/` +> (_BlockCommentOrDoc_ | ~[`*/` _IsolatedCR_])\* `*/` > > _BlockCommentOrDoc_ : >       BLOCK_COMMENT >    | OUTER_BLOCK_DOC >    | INNER_BLOCK_DOC +> +> _IsolatedCR_ : +>    _A `\r` not followed by a `\n`_ ## Non-doc comments @@ -50,6 +53,9 @@ 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 ```rust