Skip to content

Redo PR #24811 properly #24825

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 26, 2015
Merged

Redo PR #24811 properly #24825

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
85ee89a
Redo PR #24811 properly
Apr 25, 2015
0ea193d
Reference audit: comments and whitespace sections
Apr 25, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions src/doc/grammar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,12 +96,16 @@ explicit codepoint lists. [^inputformat]
## Special Unicode Productions

The following productions in the Rust grammar are defined in terms of Unicode
properties: `ident`, `non_null`, `non_star`, `non_eol`, `non_slash_or_star`,
`non_single_quote` and `non_double_quote`.
properties: `ident`, `non_null`, `non_eol`, `non_single_quote` and
`non_double_quote`.

### Identifiers

The `ident` production is any nonempty Unicode string of the following form:
The `ident` production is any nonempty Unicode[^non_ascii_idents] string of
the following form:

[^non_ascii_idents]: Non-ASCII characters in identifiers are currently feature
gated. This is expected to improve soon.

- The first character has property `XID_start`
- The remaining characters have property `XID_continue`
Expand All @@ -118,8 +122,6 @@ Some productions are defined by exclusion of particular Unicode characters:

- `non_null` is any single Unicode character aside from `U+0000` (null)
- `non_eol` is `non_null` restricted to exclude `U+000A` (`'\n'`)
- `non_star` is `non_null` restricted to exclude `U+002A` (`*`)
- `non_slash_or_star` is `non_null` restricted to exclude `U+002F` (`/`) and `U+002A` (`*`)
- `non_single_quote` is `non_null` restricted to exclude `U+0027` (`'`)
- `non_double_quote` is `non_null` restricted to exclude `U+0022` (`"`)

Expand Down
39 changes: 14 additions & 25 deletions src/doc/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,9 @@ explicit code point lists. [^inputformat]
provided to the grammar verifier, restricted to ASCII range, when verifying the
grammar in this document.

## Special Unicode Productions
## Identifiers

The following productions in the Rust grammar are defined in terms of Unicode
properties: `ident`, `non_null`, `non_eol`, `non_single_quote` and `non_double_quote`.

### Identifiers

The `ident` production is any nonempty Unicode[^non_ascii_idents] string of the following form:
An identifier is any nonempty Unicode[^non_ascii_idents] string of the following form:

[^non_ascii_idents]: Non-ASCII characters in identifiers are currently feature
gated. This is expected to improve soon.
Expand All @@ -86,40 +81,34 @@ that does _not_ occur in the set of [keywords](#keywords).
> character ranges used to form the more familiar C and Java language-family
> identifiers.

### Delimiter-restricted productions

Some productions are defined by exclusion of particular Unicode characters:

- `non_null` is any single Unicode character aside from `U+0000` (null)
- `non_eol` is `non_null` restricted to exclude `U+000A` (`'\n'`)
- `non_single_quote` is `non_null` restricted to exclude `U+0027` (`'`)
- `non_double_quote` is `non_null` restricted to exclude `U+0022` (`"`)

## Comments

Comments in Rust code follow the general C++ style of line and block-comment
forms. Nested block comments are supported.
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 beginning with exactly one repeated asterisk in the block-open
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does /// Foo really expand to #[doc = "/// Foo"]? @chris-morgan states it expands to #[doc = " Foo"].

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. I see no reason why Chris Morgan would be wrong. I just didn't think to try it out (honestly didn't even see the triple slash!). I'm currently in the middle of a build, so I can't even check...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Meh, rustc --pretty does not show any #[doc] attributes, it just regurgitates the triple-slash comments. I don't know how else to test this, since I never worked on the compiler. But since it's clearly not visible for users or ordinary Rust code, I'm fine to say that this doesn't really matter. But since section 6.3.7 (Miscellaneous attributes) does strip the triple slashes, I'll remove them here too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know. What it says seems kinda weird though. You could probably try manually inputting it like: #[doc = "/// Foo"] and see what rustdoc spits out. That might clarify it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#[doc = "/// Foo"] results in rustdoc spitting out "/// Foo" as documentation text, so Chris Morgan is definitely right (and by extension, so is my change, yay!).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this is purely an implementation detail for now, as far as I'm concerned.

sequence (`/**`), are interpreted as a special syntax for `doc`
[attributes](#attributes). That is, they are equivalent to writing
`#[doc="..."]` around the body of the comment (this includes the comment
characters themselves, i.e. `/// Foo` turns into `#[doc="/// Foo"]`).
`#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into
`#[doc="Foo"]`.

Line comments beginning with `//!` and block comments beginning with `/*!` 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 display
information on the crate index page.
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.

## Whitespace

The `whitespace_char` production is any nonempty Unicode string consisting of
any of the following Unicode characters: `U+0020` (space, `' '`), `U+0009`
(tab, `'\t'`), `U+000A` (LF, `'\n'`), `U+000D` (CR, `'\r'`).
Whitespace is any non-empty string containing any the following characters:

- `U+0020` (space, `' '`)
- `U+0009` (tab, `'\t'`)
- `U+000A` (LF, `'\n'`)
- `U+000D` (CR, `'\r'`)

Rust is a "free-form" language, meaning that all forms of whitespace serve only
to separate _tokens_ in the grammar, and have no semantic significance.
Expand Down