Skip to content

Commit 38fa82a

Browse files
borsbors
authored
Auto merge of #33922 - estebank:doc-comment, r=alexcrichton
Specific error message for missplaced doc comments Identify when documetation comments have been missplaced in the following places: * After a struct element: ```rust // file.rs: struct X { a: u8 /** document a */, } ``` ```bash $ rustc file.rs file.rs:2:11: 2:28 error: found documentation comment that doesn't document anything file.rs:2 a: u8 /** document a */, ^~~~~~~~~~~~~~~~~ file.rs:2:11: 2:28 help: doc comments must come before what they document, maybe a comment was intended with `//`? ``` * As the last line of a struct: ```rust // file.rs: struct X { a: u8, /// incorrect documentation } ``` ```bash $ rustc file.rs file.rs:3:5: 3:27 error: found a documentation comment that doesn't document anything file.rs:3 /// incorrect documentation ^~~~~~~~~~~~~~~~~~~~~~ file.rs:3:5: 3:27 help: doc comments must come before what they document, maybe a comment was intended with `//`? ``` * As the last line of a `fn`: ```rust // file.rs: fn main() { let x = 1; /// incorrect documentation } ``` ```bash $ rustc file.rs file.rs:3:5: 3:27 error: found a documentation comment that doesn't document anything file.rs:3 /// incorrect documentation ^~~~~~~~~~~~~~~~~~~~~~ file.rs:3:5: 3:27 help: doc comments must come before what they document, maybe a comment was intended with `//`? ``` Fix #27429, #30322
2 parents f883b0b + c8498cc commit 38fa82a

12 files changed

+169
-20
lines changed

‎src/librustc_errors/lib.rs

+9
Original file line numberDiff line numberDiff line change
@@ -564,6 +564,15 @@ impl Handler {
564564
self.bump_err_count();
565565
self.panic_if_treat_err_as_bug();
566566
}
567+
pub fn mut_span_err<'a, S: Into<MultiSpan>>(&'a self,
568+
sp: S,
569+
msg: &str)
570+
-> DiagnosticBuilder<'a> {
571+
let mut result = DiagnosticBuilder::new(self, Level::Error, msg);
572+
result.set_span(sp);
573+
self.bump_err_count();
574+
result
575+
}
567576
pub fn span_err_with_code<S: Into<MultiSpan>>(&self, sp: S, msg: &str, code: &str) {
568577
self.emit_with_code(&sp.into(), msg, code, Error);
569578
self.bump_err_count();

‎src/libsyntax/parse/parser.rs

+36-16
Original file line numberDiff line numberDiff line change
@@ -520,12 +520,21 @@ impl<'a> Parser<'a> {
520520
self.bug("ident interpolation not converted to real token");
521521
}
522522
_ => {
523-
let mut err = self.fatal(&format!("expected identifier, found `{}`",
524-
self.this_token_to_string()));
525-
if self.token == token::Underscore {
526-
err.note("`_` is a wildcard pattern, not an identifier");
527-
}
528-
Err(err)
523+
let last_token = self.last_token.clone().map(|t| *t);
524+
Err(match last_token {
525+
Some(token::DocComment(_)) => self.span_fatal_help(self.last_span,
526+
"found a documentation comment that doesn't document anything",
527+
"doc comments must come before what they document, maybe a comment was \
528+
intended with `//`?"),
529+
_ => {
530+
let mut err = self.fatal(&format!("expected identifier, found `{}`",
531+
self.this_token_to_string()));
532+
if self.token == token::Underscore {
533+
err.note("`_` is a wildcard pattern, not an identifier");
534+
}
535+
err
536+
}
537+
})
529538
}
530539
}
531540
}
@@ -927,6 +936,7 @@ impl<'a> Parser<'a> {
927936
// Stash token for error recovery (sometimes; clone is not necessarily cheap).
928937
self.last_token = if self.token.is_ident() ||
929938
self.token.is_path() ||
939+
self.token.is_doc_comment() ||
930940
self.token == token::Comma {
931941
Some(Box::new(self.token.clone()))
932942
} else {
@@ -1018,6 +1028,11 @@ impl<'a> Parser<'a> {
10181028
pub fn span_err(&self, sp: Span, m: &str) {
10191029
self.sess.span_diagnostic.span_err(sp, m)
10201030
}
1031+
pub fn span_err_help(&self, sp: Span, m: &str, h: &str) {
1032+
let mut err = self.sess.span_diagnostic.mut_span_err(sp, m);
1033+
err.help(h);
1034+
err.emit();
1035+
}
10211036
pub fn span_bug(&self, sp: Span, m: &str) -> ! {
10221037
self.sess.span_diagnostic.span_bug(sp, m)
10231038
}
@@ -4021,8 +4036,14 @@ impl<'a> Parser<'a> {
40214036
None => {
40224037
let unused_attrs = |attrs: &[_], s: &mut Self| {
40234038
if attrs.len() > 0 {
4024-
s.span_err(s.span,
4025-
"expected statement after outer attribute");
4039+
let last_token = s.last_token.clone().map(|t| *t);
4040+
match last_token {
4041+
Some(token::DocComment(_)) => s.span_err_help(s.last_span,
4042+
"found a documentation comment that doesn't document anything",
4043+
"doc comments must come before what they document, maybe a \
4044+
comment was intended with `//`?"),
4045+
_ => s.span_err(s.span, "expected statement after outer attribute"),
4046+
}
40264047
}
40274048
};
40284049

@@ -5127,14 +5148,13 @@ impl<'a> Parser<'a> {
51275148
self.bump();
51285149
}
51295150
token::CloseDelim(token::Brace) => {}
5130-
_ => {
5131-
let span = self.span;
5132-
let token_str = self.this_token_to_string();
5133-
return Err(self.span_fatal_help(span,
5134-
&format!("expected `,`, or `}}`, found `{}`",
5135-
token_str),
5136-
"struct fields should be separated by commas"))
5137-
}
5151+
token::DocComment(_) => return Err(self.span_fatal_help(self.span,
5152+
"found a documentation comment that doesn't document anything",
5153+
"doc comments must come before what they document, maybe a comment was \
5154+
intended with `//`?")),
5155+
_ => return Err(self.span_fatal_help(self.span,
5156+
&format!("expected `,`, or `}}`, found `{}`", self.this_token_to_string()),
5157+
"struct fields should be separated by commas")),
51385158
}
51395159
Ok(a_var)
51405160
}

‎src/libsyntax/parse/token.rs

+9-1
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ impl Token {
203203
pub fn is_lit(&self) -> bool {
204204
match *self {
205205
Literal(_, _) => true,
206-
_ => false,
206+
_ => false,
207207
}
208208
}
209209

@@ -215,6 +215,14 @@ impl Token {
215215
}
216216
}
217217

218+
/// Returns `true` if the token is a documentation comment.
219+
pub fn is_doc_comment(&self) -> bool {
220+
match *self {
221+
DocComment(..) => true,
222+
_ => false,
223+
}
224+
}
225+
218226
/// Returns `true` if the token is interpolated.
219227
pub fn is_interpolated(&self) -> bool {
220228
match *self {

‎src/test/parse-fail/doc-after-struct-field.rs

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
// compile-flags: -Z continue-parse-after-error
12+
struct X {
13+
a: u8 /** document a */,
14+
//~^ ERROR found a documentation comment that doesn't document anything
15+
//~| HELP maybe a comment was intended
16+
}
17+
18+
fn main() {
19+
let y = X {a = 1};
20+
}

‎src/test/parse-fail/doc-before-extern-rbrace.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,5 @@
1212

1313
extern {
1414
/// hi
15+
//~^ ERROR expected item after doc comment
1516
}
16-
//~^^ ERROR expected item after doc comment

‎src/test/parse-fail/doc-before-fn-rbrace.rs

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
// compile-flags: -Z continue-parse-after-error
12+
fn main() {
13+
/// document
14+
//~^ ERROR found a documentation comment that doesn't document anything
15+
//~| HELP maybe a comment was intended
16+
}

‎src/test/parse-fail/doc-before-identifier.rs

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
// compile-flags: -Z continue-parse-after-error
12+
fn /// document
13+
foo() {}
14+
//~^^ ERROR expected identifier, found `/// document`
15+
16+
fn main() {
17+
foo();
18+
}

‎src/test/parse-fail/doc-before-mod-rbrace.rs

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
// compile-flags: -Z continue-parse-after-error
12+
mod Foo {
13+
/// document
14+
//~^ ERROR expected item after doc comment
15+
}

‎src/test/parse-fail/doc-before-rbrace.rs

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,6 @@
1212

1313
fn main() {
1414
println!("Hi"); /// hi
15+
//~^ ERROR found a documentation comment that doesn't document anything
16+
//~| HELP maybe a comment was intended
1517
}
16-
//~^ ERROR expected statement

‎src/test/parse-fail/doc-before-semi.rs

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212

1313
fn main() {
1414
/// hi
15+
//~^ ERROR found a documentation comment that doesn't document anything
16+
//~| HELP maybe a comment was intended
1517
;
16-
//~^ ERROR expected statement
1718
}

‎src/test/parse-fail/doc-before-struct-rbrace-1.rs

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
// compile-flags: -Z continue-parse-after-error
12+
struct X {
13+
a: u8,
14+
/// document
15+
//~^ ERROR found a documentation comment that doesn't document anything
16+
//~| HELP maybe a comment was intended
17+
}
18+
19+
fn main() {
20+
let y = X {a = 1};
21+
}

‎src/test/parse-fail/doc-before-struct-rbrace-2.rs

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
// compile-flags: -Z continue-parse-after-error
12+
struct X {
13+
a: u8 /// document
14+
//~^ ERROR found a documentation comment that doesn't document anything
15+
//~| HELP maybe a comment was intended
16+
}
17+
18+
fn main() {
19+
let y = X {a = 1};
20+
}

0 commit comments

Comments
 (0)