Be more strict about doc comments

[emberian]

Previously, //// foo and /*** foo ***/ were accepted as doc comments. This
changes that, so that only /// foo and /** foo ***/ are accepted. This
confuses many newcomers and it seems weird.

Also update the manual for these changes, and modernify the EBNF for comments.

Closes #10638

[sfackler]

Shouldn't this be #[doc="Foo"]?

[emberian]

No.

On Sun, Nov 24, 2013 at 11:34 PM, Steven Fackler
[email protected]:

In doc/rust.md:

line_comment : "//" non_eol * ;

 Comments in Rust code follow the general C++ style of line and block-comment forms,
 with no nesting of block-comment delimiters.

-Line comments beginning with _three_ slashes (`///`),
-and block comments beginning with a 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 comment's text.
+Line comments beginning with exactly _three_ slashes (`///`), and block
+comments beginning with a 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, ie `/// Foo` turns into `#[doc="/// Foo"]`.

Shouldn't this be #[doc="Foo"]?

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/10642/files#r7882777
.

[emberian]

(That's exactly what this parenthetical is clarifying)

On Sun, Nov 24, 2013 at 11:35 PM, Corey Richardson [email protected] wrote:

No.

On Sun, Nov 24, 2013 at 11:34 PM, Steven Fackler <[email protected]

wrote:

In doc/rust.md:

line_comment : "//" non_eol * ;

 Comments in Rust code follow the general C++ style of line and block-comment forms,
 with no nesting of block-comment delimiters.

-Line comments beginning with _three_ slashes (`///`),
-and block comments beginning with a 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 comment's text.
+Line comments beginning with exactly _three_ slashes (`///`), and block
+comments beginning with a 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, ie `/// Foo` turns into `#[doc="/// Foo"]`.

Shouldn't this be #[doc="Foo"]?

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/10642/files#r7882777
.

[alexcrichton]

We decided today that this is a good idea. r=me with a rebase.

[chris-morgan]

diff --git a/src/etc/vim/syntax/rust.vim b/src/etc/vim/syntax/rust.vim
index e5ff089..dc1e58c 100644
--- a/src/etc/vim/syntax/rust.vim
+++ b/src/etc/vim/syntax/rust.vim
@@ -187,8 +187,8 @@ syn match   rustCharacter   /'\([^'\\]\|\\\([nrt0\\'"]\|x\x\{2}\|u\x\{4}\|U\x\{8

 syn region    rustCommentML   start="/\*" end="\*/" contains=rustTodo
 syn region    rustComment     start="//" end="$" contains=rustTodo keepend
-syn region    rustCommentMLDoc start="/\*\%(!\|\*/\@!\)" end="\*/" contains=rustTodo
-syn region    rustCommentDoc  start="//[/!]" end="$" contains=rustTodo keepend
+syn region    rustCommentMLDoc start="/\*\%(!\|\*[*/]\@!\)" end="\*/" contains=rustTodo
+syn region    rustCommentDoc  start="//\%(//\@!\|!\)" end="$" contains=rustTodo keepend

 syn keyword rustTodo contained TODO FIXME XXX NB NOTE

This fixes the Vim syntax file to match these new semantics. (Nested comments I will add separately.)

(P.S. When making changes which affect the grammar, I would really like it if the text editor configurations were also updated at that time, when it's easiest.)

[emberian]

Thanks, @chris-morgan. I don't really know regex well, and certainly not all of the various text editors' various configuations. What can we do to improve our process in this regard?

[chris-morgan]

@cmr often, changes will be obvious (e.g. adding new keywords, or prelude changes—the prelude items are contained in the Vim syntax file). Where it's not, it's probably best to assign certain regions deemed to have such cases to specific people. For example, I'd be delighted to accept responsibility for the Vim config, so that any time there is anything which will require work on the Vim config the author or reviewer (I believe review needs to be more thorough than it typically is, a surprising number of problems have been creeping through) will mention me and I'll come and help.

Maintaining a tree of responsibility (separately) might work:

+ mk/: Person X
+ src/: brson
  + librustc/
  + libstd/
    + somefile.rs: Another Person
  + etc/
    + vim/: Chris Morgan

This would have the added benefit of making it clear who someone should talk to about changes to a certain area of the code base.

Of course, that uncovers the nest of decaying code which has no owner and is in fact unmaintained and often in consequence buggy and broken.

This is now distinctly out of scope for this issue. I shall raise it on the mailing list.