Add support to grammar for single line comments #1993

traviscross · 2025-09-07T09:57:31Z

Sometimes it would be useful in the grammar to be able to add comments inline. Let's allow this.

We'll treat these comments as expressions and add special handling to allow these on lines ahead of the production name.

For now we'll render these only in the Markdown and not in the railroad diagrams.

This is best reviewed commit by commit.

cc @ehuss

Some CSS rules were missing a trailing semicolon. Let's add this where it was missing.

When defining colors relative to other colors defined per theme, it's helpful to have these all defined as variables and have all the variables defined in one place. Let's do that.

Sometimes it would be useful in the grammar to be able to add comments inline. Let's allow this. We'll treat these comments as expressions and add special handling to allow these on lines ahead of the production name. For now we'll render these only in the Markdown and not in the railroad diagrams.

ehuss

Thanks!

A remark I have is that there is pretty broad inconsistency on how different groups and tools define comments. The ones I'm aware of are:

IETF — ;
ISO — (* ... *)
W3C — ; and /* .. */
ANTLR, Bison — // and /* .. */

Most grammars for languages that I've seen do not have comments.

Staying familiar with Rust syntax is probably the best choice here.

I'll also mention that it now becomes a little unclear if certain comments should be attached with a footnote or a comment. We'll see how that plays out.

Update books ## rust-lang/book 1 commits in 3e9dc46aa563ca0c53ec826c41b05f10c5915925..33f1af40cc44dde7e3e892f7a508e6f427d2cbc6 2025-09-15 16:10:14 UTC to 2025-09-15 16:10:14 UTC - Release trpl 0.3 (rust-lang/book#4505) ## rust-lang/reference 9 commits in b3ce60628c6f55ab8ff3dba9f3d20203df1c0dee..cc7247d8dfaef4c39000bb12c55c32ba5b5ba976 2025-09-20 10:26:26 UTC to 2025-09-08 18:07:29 UTC - Document temporary scoping for destructuring assignments (rust-lang/reference#1992) - Specify lifetime extension of `pin!` and `format_args!` arguments (rust-lang/reference#1980) - update for more ABIs supporting c-variadics (rust-lang/reference#1936) - Fix incorrect span tag (rust-lang/reference#1995) - Remove strike attribute (rust-lang/reference#1997) - Specify the target limits for target-specific ABIs (rust-lang/reference#2000) - Remove tuple index carve out (rust-lang/reference#1966) - Enable folding of chapter listing in navigation sidebar (rust-lang/reference#1988) - Add support to grammar for single line comments (rust-lang/reference#1993) ## rust-lang/rust-by-example 1 commits in dd26bc8e726dc2e73534c8972d4dccd1bed7495f..2c9b490d70e535cf166bf17feba59e594579843f 2025-09-18 22:28:52 UTC to 2025-09-18 22:28:52 UTC - Update unit testing output for additional test (rust-lang/rust-by-example#1958)

Rollup merge of #146898 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 1 commits in 3e9dc46aa563ca0c53ec826c41b05f10c5915925..33f1af40cc44dde7e3e892f7a508e6f427d2cbc6 2025-09-15 16:10:14 UTC to 2025-09-15 16:10:14 UTC - Release trpl 0.3 (rust-lang/book#4505) ## rust-lang/reference 9 commits in b3ce60628c6f55ab8ff3dba9f3d20203df1c0dee..cc7247d8dfaef4c39000bb12c55c32ba5b5ba976 2025-09-20 10:26:26 UTC to 2025-09-08 18:07:29 UTC - Document temporary scoping for destructuring assignments (rust-lang/reference#1992) - Specify lifetime extension of `pin!` and `format_args!` arguments (rust-lang/reference#1980) - update for more ABIs supporting c-variadics (rust-lang/reference#1936) - Fix incorrect span tag (rust-lang/reference#1995) - Remove strike attribute (rust-lang/reference#1997) - Specify the target limits for target-specific ABIs (rust-lang/reference#2000) - Remove tuple index carve out (rust-lang/reference#1966) - Enable folding of chapter listing in navigation sidebar (rust-lang/reference#1988) - Add support to grammar for single line comments (rust-lang/reference#1993) ## rust-lang/rust-by-example 1 commits in dd26bc8e726dc2e73534c8972d4dccd1bed7495f..2c9b490d70e535cf166bf17feba59e594579843f 2025-09-18 22:28:52 UTC to 2025-09-18 22:28:52 UTC - Update unit testing output for additional test (rust-lang/rust-by-example#1958)

Update books ## rust-lang/book 1 commits in 3e9dc46aa563ca0c53ec826c41b05f10c5915925..33f1af40cc44dde7e3e892f7a508e6f427d2cbc6 2025-09-15 16:10:14 UTC to 2025-09-15 16:10:14 UTC - Release trpl 0.3 (rust-lang/book#4505) ## rust-lang/reference 9 commits in b3ce60628c6f55ab8ff3dba9f3d20203df1c0dee..cc7247d8dfaef4c39000bb12c55c32ba5b5ba976 2025-09-20 10:26:26 UTC to 2025-09-08 18:07:29 UTC - Document temporary scoping for destructuring assignments (rust-lang/reference#1992) - Specify lifetime extension of `pin!` and `format_args!` arguments (rust-lang/reference#1980) - update for more ABIs supporting c-variadics (rust-lang/reference#1936) - Fix incorrect span tag (rust-lang/reference#1995) - Remove strike attribute (rust-lang/reference#1997) - Specify the target limits for target-specific ABIs (rust-lang/reference#2000) - Remove tuple index carve out (rust-lang/reference#1966) - Enable folding of chapter listing in navigation sidebar (rust-lang/reference#1988) - Add support to grammar for single line comments (rust-lang/reference#1993) ## rust-lang/rust-by-example 1 commits in dd26bc8e726dc2e73534c8972d4dccd1bed7495f..2c9b490d70e535cf166bf17feba59e594579843f 2025-09-18 22:28:52 UTC to 2025-09-18 22:28:52 UTC - Update unit testing output for additional test (rust-lang/rust-by-example#1958)

traviscross added 3 commits September 7, 2025 01:55

Clean up whitespace in reference.css

f9c43be

Add trailing semicolon to CSS rules missing one

0e6e036

Some CSS rules were missing a trailing semicolon. Let's add this where it was missing.

Move per-theme CSS variables to top

890caa2

When defining colors relative to other colors defined per theme, it's helpful to have these all defined as variables and have all the variables defined in one place. Let's do that.

rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Sep 7, 2025

traviscross mentioned this pull request Sep 7, 2025

Create Whitespace grammar productions #1991

Merged

traviscross force-pushed the TC/add-grammar-comments-support branch from 00b2e0e to bf5d0d5 Compare September 7, 2025 10:17

traviscross changed the title ~~Add support to grammar for single line comments~~ Add grammar support for single line comments Sep 7, 2025

traviscross changed the title ~~Add grammar support for single line comments~~ Add support to grammar for single line comments Sep 7, 2025

traviscross force-pushed the TC/add-grammar-comments-support branch from bf5d0d5 to b3b582c Compare September 7, 2025 10:18

ehuss approved these changes Sep 8, 2025

View reviewed changes

ehuss added this pull request to the merge queue Sep 8, 2025

Merged via the queue into master with commit f82156b Sep 8, 2025
5 checks passed

rustbot removed the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Sep 8, 2025

rustbot mentioned this pull request Sep 22, 2025

Update books rust-lang/rust#146898

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add support to grammar for single line comments #1993

Add support to grammar for single line comments #1993

Uh oh!

traviscross commented Sep 7, 2025

Uh oh!

ehuss left a comment

Uh oh!

Uh oh!

Uh oh!

Add support to grammar for single line comments #1993

Add support to grammar for single line comments #1993

Uh oh!

Conversation

traviscross commented Sep 7, 2025

Uh oh!

ehuss left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!