Be more strict about doc comments

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

Author: emberian

doc/rust.md

@@ -153,17 +153,19 @@ Some productions are defined by exclusion of particular Unicode characters:
 ~~~~ {.ebnf .gram}
 comment : block_comment | line_comment ;
 block_comment : "/*" block_comment_body * '*' + '/' ;
-block_comment_body : non_star * | '*' + non_slash_or_star ;
+block_comment_body : (block_comment | character) * ;
 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"]`).
 
 Non-doc comments are interpreted as a form of whitespace.
 

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
 

src/libsyntax/parse/lexer.rs

@@ -317,8 +317,7 @@ fn consume_whitespace_and_comments(rdr: @mut StringReader)
 }
 
 pub fn is_line_non_doc_comment(s: &str) -> bool {
-    let s = s.trim_right();
-    s.len() > 3 && s.chars().all(|ch| ch == '/')
+    s.starts_with("////")
 }
 
 // PRECONDITION: rdr.curr is not whitespace
@@ -378,8 +377,7 @@ fn consume_any_line_comment(rdr: @mut StringReader)
 }
 
 pub fn is_block_non_doc_comment(s: &str) -> bool {
-    assert!(s.len() >= 1u);
-    s.slice(1u, s.len() - 1u).chars().all(|ch| ch == '*')
+    s.starts_with("/***")
 }
 
 // might return a sugared-doc-attr

src/test/run-pass/issue-10638.rs

@@ -0,0 +1,18 @@
+// Copyright 2013 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+pub fn main() {
+    //// I am not a doc comment!
+    ////////////////// still not a doc comment
+    /////**** nope, me neither */
+    /*** And neither am I! */
+    5;
+    /*****! certainly not I */
+}