Skip to content

Commit c8498cc

Browse files
estebankestebank
committed
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
1 parent 731d375 commit c8498cc

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
@@ -578,12 +578,21 @@ impl<'a> Parser<'a> {
578578
self.bug("ident interpolation not converted to real token");
579579
}
580580
_ => {
581-
let mut err = self.fatal(&format!("expected identifier, found `{}`",
582-
self.this_token_to_string()));
583-
if self.token == token::Underscore {
584-
err.note("`_` is a wildcard pattern, not an identifier");
585-
}
586-
Err(err)
581+
let last_token = self.last_token.clone().map(|t| *t);
582+
Err(match last_token {
583+
Some(token::DocComment(_)) => self.span_fatal_help(self.last_span,
584+
"found a documentation comment that doesn't document anything",
585+
"doc comments must come before what they document, maybe a comment was \
586+
intended with `//`?"),
587+
_ => {
588+
let mut err = self.fatal(&format!("expected identifier, found `{}`",
589+
self.this_token_to_string()));
590+
if self.token == token::Underscore {
591+
err.note("`_` is a wildcard pattern, not an identifier");
592+
}
593+
err
594+
}
595+
})
587596
}
588597
}
589598
}
@@ -985,6 +994,7 @@ impl<'a> Parser<'a> {
985994
// Stash token for error recovery (sometimes; clone is not necessarily cheap).
986995
self.last_token = if self.token.is_ident() ||
987996
self.token.is_path() ||
997+
self.token.is_doc_comment() ||
988998
self.token == token::Comma {
989999
Some(Box::new(self.token.clone()))
9901000
} else {
@@ -1076,6 +1086,11 @@ impl<'a> Parser<'a> {
10761086
pub fn span_err(&self, sp: Span, m: &str) {
10771087
self.sess.span_diagnostic.span_err(sp, m)
10781088
}
1089+
pub fn span_err_help(&self, sp: Span, m: &str, h: &str) {
1090+
let mut err = self.sess.span_diagnostic.mut_span_err(sp, m);
1091+
err.help(h);
1092+
err.emit();
1093+
}
10791094
pub fn span_bug(&self, sp: Span, m: &str) -> ! {
10801095
self.sess.span_diagnostic.span_bug(sp, m)
10811096
}
@@ -4029,8 +4044,14 @@ impl<'a> Parser<'a> {
40294044
None => {
40304045
let unused_attrs = |attrs: &[_], s: &mut Self| {
40314046
if attrs.len() > 0 {
4032-
s.span_err(s.span,
4033-
"expected statement after outer attribute");
4047+
let last_token = s.last_token.clone().map(|t| *t);
4048+
match last_token {
4049+
Some(token::DocComment(_)) => s.span_err_help(s.last_span,
4050+
"found a documentation comment that doesn't document anything",
4051+
"doc comments must come before what they document, maybe a \
4052+
comment was intended with `//`?"),
4053+
_ => s.span_err(s.span, "expected statement after outer attribute"),
4054+
}
40344055
}
40354056
};
40364057

@@ -5198,14 +5219,13 @@ impl<'a> Parser<'a> {
51985219
self.bump();
51995220
}
52005221
token::CloseDelim(token::Brace) => {}
5201-
_ => {
5202-
let span = self.span;
5203-
let token_str = self.this_token_to_string();
5204-
return Err(self.span_fatal_help(span,
5205-
&format!("expected `,`, or `}}`, found `{}`",
5206-
token_str),
5207-
"struct fields should be separated by commas"))
5208-
}
5222+
token::DocComment(_) => return Err(self.span_fatal_help(self.span,
5223+
"found a documentation comment that doesn't document anything",
5224+
"doc comments must come before what they document, maybe a comment was \
5225+
intended with `//`?")),
5226+
_ => return Err(self.span_fatal_help(self.span,
5227+
&format!("expected `,`, or `}}`, found `{}`", self.this_token_to_string()),
5228+
"struct fields should be separated by commas")),
52095229
}
52105230
Ok(a_var)
52115231
}

‎src/libsyntax/parse/token.rs

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

@@ -214,6 +214,14 @@ impl Token {
214214
}
215215
}
216216

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