From 0ea193def9e637ed333ce83a4902cf90c42d9381 Mon Sep 17 00:00:00 2001 From: Robin Kruppe Date: Sun, 26 Apr 2015 00:03:59 +0200 Subject: [PATCH] Reference audit: comments and whitespace sections --- src/doc/reference.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index 93440694cd89..7c9cca90edda 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -83,29 +83,32 @@ that does _not_ occur in the set of [keywords](#keywords). ## 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 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.