OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Be more strict about doc comments

Browse Source 
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
This commit is contained in:
Corey Richardson 2013-11-24 23:23:50 -05:00
parent e147a090a5
commit b50b162884
4 changed files with 29 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/rust.md
View File

@ -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.

4
src/etc/vim/syntax/rust.vim
View File

@ -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

6
src/libsyntax/parse/lexer.rs
View File

@ -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

18
src/test/run-pass/issue-10638.rs Normal file
View File

@ -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 */
}