Skip to content

Commit 086eb47

Browse files
JohnTitorJohnTitor
committed
Add a help message to unused_doc_comments lint
1 parent ce331ee commit 086eb47

File tree

4 files changed

+119
-2
lines changed

4 files changed

+119
-2
lines changed

‎compiler/rustc_lint/src/builtin.rs

+13-2
Original file line numberDiff line numberDiff line change
@@ -984,13 +984,16 @@ impl EarlyLintPass for DeprecatedAttr {
984984
}
985985

986986
fn warn_if_doc(cx: &EarlyContext<'_>, node_span: Span, node_kind: &str, attrs: &[ast::Attribute]) {
987+
use rustc_ast::token::CommentKind;
988+
987989
let mut attrs = attrs.iter().peekable();
988990

989991
// Accumulate a single span for sugared doc comments.
990992
let mut sugared_span: Option<Span> = None;
991993

992994
while let Some(attr) = attrs.next() {
993-
if attr.is_doc_comment() {
995+
let is_doc_comment = attr.is_doc_comment();
996+
if is_doc_comment {
994997
sugared_span =
995998
Some(sugared_span.map_or(attr.span, |span| span.with_hi(attr.span.hi())));
996999
}
@@ -1001,13 +1004,21 @@ fn warn_if_doc(cx: &EarlyContext<'_>, node_span: Span, node_kind: &str, attrs: &
10011004

10021005
let span = sugared_span.take().unwrap_or(attr.span);
10031006

1004-
if attr.is_doc_comment() || cx.sess().check_name(attr, sym::doc) {
1007+
if is_doc_comment || cx.sess().check_name(attr, sym::doc) {
10051008
cx.struct_span_lint(UNUSED_DOC_COMMENTS, span, |lint| {
10061009
let mut err = lint.build("unused doc comment");
10071010
err.span_label(
10081011
node_span,
10091012
format!("rustdoc does not generate documentation for {}", node_kind),
10101013
);
1014+
match attr.kind {
1015+
AttrKind::DocComment(CommentKind::Line, _) | AttrKind::Normal(..) => {
1016+
err.help("use `//` for a plain comment");
1017+
}
1018+
AttrKind::DocComment(CommentKind::Block, _) => {
1019+
err.help("use `/* */` for a plain comment");
1020+
}
1021+
}
10111022
err.emit();
10121023
});
10131024
}

‎src/test/ui/unused/unused-doc-comments-edge-cases.rs

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#![deny(unused_doc_comments)]
2+
3+
fn doc_comment_on_match_arms(num: u8) -> bool {
4+
match num {
5+
3 => true,
6+
/// useless doc comment
7+
//~^ ERROR: unused doc comment
8+
_ => false,
9+
}
10+
}
11+
12+
fn doc_comment_between_if_else(num: u8) -> bool {
13+
if num == 3 {
14+
true //~ ERROR: mismatched types
15+
}
16+
/// useless doc comment
17+
else { //~ ERROR: expected expression, found keyword `else`
18+
false
19+
}
20+
}
21+
22+
fn doc_comment_on_expr(num: u8) -> bool {
23+
/// useless doc comment
24+
//~^ ERROR: attributes on expressions are experimental
25+
//~| ERROR: unused doc comment
26+
num == 3
27+
}
28+
29+
fn main() {}

‎src/test/ui/unused/unused-doc-comments-edge-cases.stderr

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
error: expected expression, found keyword `else`
2+
--> $DIR/unused-doc-comments-edge-cases.rs:17:5
3+
|
4+
LL | else {
5+
| ^^^^ expected expression
6+
7+
error[E0658]: attributes on expressions are experimental
8+
--> $DIR/unused-doc-comments-edge-cases.rs:23:5
9+
|
10+
LL | /// useless doc comment
11+
| ^^^^^^^^^^^^^^^^^^^^^^^
12+
|
13+
= note: see issue #15701 <https://github.com/rust-lang/rust/issues/15701> for more information
14+
= help: add `#![feature(stmt_expr_attributes)]` to the crate attributes to enable
15+
= help: `///` is for documentation comments. For a plain comment, use `//`.
16+
17+
error: unused doc comment
18+
--> $DIR/unused-doc-comments-edge-cases.rs:6:9
19+
|
20+
LL | /// useless doc comment
21+
| ^^^^^^^^^^^^^^^^^^^^^^^
22+
LL |
23+
LL | _ => false,
24+
| ---------- rustdoc does not generate documentation for match arms
25+
|
26+
note: the lint level is defined here
27+
--> $DIR/unused-doc-comments-edge-cases.rs:1:9
28+
|
29+
LL | #![deny(unused_doc_comments)]
30+
| ^^^^^^^^^^^^^^^^^^^
31+
= help: use `//` for a plain comment
32+
33+
error: unused doc comment
34+
--> $DIR/unused-doc-comments-edge-cases.rs:23:5
35+
|
36+
LL | /// useless doc comment
37+
| ^^^^^^^^^^^^^^^^^^^^^^^
38+
...
39+
LL | num == 3
40+
| --- rustdoc does not generate documentation for expressions
41+
|
42+
= help: use `//` for a plain comment
43+
44+
error[E0308]: mismatched types
45+
--> $DIR/unused-doc-comments-edge-cases.rs:14:9
46+
|
47+
LL | / if num == 3 {
48+
LL | | true
49+
| | ^^^^ expected `()`, found `bool`
50+
LL | | }
51+
| |_____- expected this to be `()`
52+
|
53+
help: you might have meant to return this value
54+
|
55+
LL | return true;
56+
| ^^^^^^ ^
57+
58+
error: aborting due to 5 previous errors
59+
60+
Some errors have detailed explanations: E0308, E0658.
61+
For more information about an error, try `rustc --explain E0308`.

‎src/test/ui/unused/useless-comment.stderr

+16
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ LL | /// a
2626
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2727
LL | let x = 12;
2828
| ----------- rustdoc does not generate documentation for statements
29+
|
30+
= help: use `//` for a plain comment
2931

3032
error: unused doc comment
3133
--> $DIR/useless-comment.rs:16:5
@@ -40,6 +42,8 @@ LL | | 1 => {},
4042
LL | | _ => {}
4143
LL | | }
4244
| |_____- rustdoc does not generate documentation for expressions
45+
|
46+
= help: use `//` for a plain comment
4347

4448
error: unused doc comment
4549
--> $DIR/useless-comment.rs:20:9
@@ -48,6 +52,8 @@ LL | /// c
4852
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4953
LL | 1 => {},
5054
| ------- rustdoc does not generate documentation for match arms
55+
|
56+
= help: use `//` for a plain comment
5157

5258
error: unused doc comment
5359
--> $DIR/useless-comment.rs:25:5
@@ -56,6 +62,8 @@ LL | /// foo
5662
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5763
LL | unsafe {}
5864
| --------- rustdoc does not generate documentation for expressions
65+
|
66+
= help: use `//` for a plain comment
5967

6068
error: unused doc comment
6169
--> $DIR/useless-comment.rs:28:5
@@ -65,6 +73,8 @@ LL | #[doc = "foo"]
6573
LL | #[doc = "bar"]
6674
LL | 3;
6775
| - rustdoc does not generate documentation for expressions
76+
|
77+
= help: use `//` for a plain comment
6878

6979
error: unused doc comment
7080
--> $DIR/useless-comment.rs:29:5
@@ -73,12 +83,16 @@ LL | #[doc = "bar"]
7383
| ^^^^^^^^^^^^^^
7484
LL | 3;
7585
| - rustdoc does not generate documentation for expressions
86+
|
87+
= help: use `//` for a plain comment
7688

7789
error: unused doc comment
7890
--> $DIR/useless-comment.rs:35:13
7991
|
8092
LL | let x = /** comment */ 47;
8193
| ^^^^^^^^^^^^^^ -- rustdoc does not generate documentation for expressions
94+
|
95+
= help: use `/* */` for a plain comment
8296

8397
error: unused doc comment
8498
--> $DIR/useless-comment.rs:37:5
@@ -89,6 +103,8 @@ LL | / {
89103
LL | |
90104
LL | | }
91105
| |_____- rustdoc does not generate documentation for expressions
106+
|
107+
= help: use `//` for a plain comment
92108

93109
error: aborting due to 10 previous errors
94110

0 commit comments

Comments
 (0)