}
fn warn_if_doc(cx: &EarlyContext<'_>, node_span: Span, node_kind: &str, attrs: &[ast::Attribute]) {
+ use rustc_ast::token::CommentKind;
+
let mut attrs = attrs.iter().peekable();
// Accumulate a single span for sugared doc comments.
let mut sugared_span: Option<Span> = None;
while let Some(attr) = attrs.next() {
- if attr.is_doc_comment() {
+ let is_doc_comment = attr.is_doc_comment();
+ if is_doc_comment {
sugared_span =
Some(sugared_span.map_or(attr.span, |span| span.with_hi(attr.span.hi())));
}
let span = sugared_span.take().unwrap_or(attr.span);
- if attr.is_doc_comment() || cx.sess().check_name(attr, sym::doc) {
+ if is_doc_comment || cx.sess().check_name(attr, sym::doc) {
cx.struct_span_lint(UNUSED_DOC_COMMENTS, span, |lint| {
let mut err = lint.build("unused doc comment");
err.span_label(
node_span,
format!("rustdoc does not generate documentation for {}", node_kind),
);
+ match attr.kind {
+ AttrKind::DocComment(CommentKind::Line, _) | AttrKind::Normal(..) => {
+ err.help("use `//` for a plain comment");
+ }
+ AttrKind::DocComment(CommentKind::Block, _) => {
+ err.help("use `/* */` for a plain comment");
+ }
+ }
err.emit();
});
}
--- /dev/null
+#![deny(unused_doc_comments)]
+
+fn doc_comment_on_match_arms(num: u8) -> bool {
+ match num {
+ 3 => true,
+ /// useless doc comment
+ //~^ ERROR: unused doc comment
+ _ => false,
+ }
+}
+
+fn doc_comment_between_if_else(num: u8) -> bool {
+ if num == 3 {
+ true //~ ERROR: mismatched types
+ }
+ /// useless doc comment
+ else { //~ ERROR: expected expression, found keyword `else`
+ false
+ }
+}
+
+fn doc_comment_on_expr(num: u8) -> bool {
+ /// useless doc comment
+ //~^ ERROR: attributes on expressions are experimental
+ //~| ERROR: unused doc comment
+ num == 3
+}
+
+fn main() {}
--- /dev/null
+error: expected expression, found keyword `else`
+ --> $DIR/unused-doc-comments-edge-cases.rs:17:5
+ |
+LL | else {
+ | ^^^^ expected expression
+
+error[E0658]: attributes on expressions are experimental
+ --> $DIR/unused-doc-comments-edge-cases.rs:23:5
+ |
+LL | /// useless doc comment
+ | ^^^^^^^^^^^^^^^^^^^^^^^
+ |
+ = note: see issue #15701 <https://github.com/rust-lang/rust/issues/15701> for more information
+ = help: add `#![feature(stmt_expr_attributes)]` to the crate attributes to enable
+ = help: `///` is for documentation comments. For a plain comment, use `//`.
+
+error: unused doc comment
+ --> $DIR/unused-doc-comments-edge-cases.rs:6:9
+ |
+LL | /// useless doc comment
+ | ^^^^^^^^^^^^^^^^^^^^^^^
+LL |
+LL | _ => false,
+ | ---------- rustdoc does not generate documentation for match arms
+ |
+note: the lint level is defined here
+ --> $DIR/unused-doc-comments-edge-cases.rs:1:9
+ |
+LL | #![deny(unused_doc_comments)]
+ | ^^^^^^^^^^^^^^^^^^^
+ = help: use `//` for a plain comment
+
+error: unused doc comment
+ --> $DIR/unused-doc-comments-edge-cases.rs:23:5
+ |
+LL | /// useless doc comment
+ | ^^^^^^^^^^^^^^^^^^^^^^^
+...
+LL | num == 3
+ | --- rustdoc does not generate documentation for expressions
+ |
+ = help: use `//` for a plain comment
+
+error[E0308]: mismatched types
+ --> $DIR/unused-doc-comments-edge-cases.rs:14:9
+ |
+LL | / if num == 3 {
+LL | | true
+ | | ^^^^ expected `()`, found `bool`
+LL | | }
+ | |_____- expected this to be `()`
+ |
+help: you might have meant to return this value
+ |
+LL | return true;
+ | ^^^^^^ ^
+
+error: aborting due to 5 previous errors
+
+Some errors have detailed explanations: E0308, E0658.
+For more information about an error, try `rustc --explain E0308`.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | let x = 12;
| ----------- rustdoc does not generate documentation for statements
+ |
+ = help: use `//` for a plain comment
error: unused doc comment
--> $DIR/useless-comment.rs:16:5
LL | | _ => {}
LL | | }
| |_____- rustdoc does not generate documentation for expressions
+ |
+ = help: use `//` for a plain comment
error: unused doc comment
--> $DIR/useless-comment.rs:20:9
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | 1 => {},
| ------- rustdoc does not generate documentation for match arms
+ |
+ = help: use `//` for a plain comment
error: unused doc comment
--> $DIR/useless-comment.rs:25:5
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LL | unsafe {}
| --------- rustdoc does not generate documentation for expressions
+ |
+ = help: use `//` for a plain comment
error: unused doc comment
--> $DIR/useless-comment.rs:28:5
LL | #[doc = "bar"]
LL | 3;
| - rustdoc does not generate documentation for expressions
+ |
+ = help: use `//` for a plain comment
error: unused doc comment
--> $DIR/useless-comment.rs:29:5
| ^^^^^^^^^^^^^^
LL | 3;
| - rustdoc does not generate documentation for expressions
+ |
+ = help: use `//` for a plain comment
error: unused doc comment
--> $DIR/useless-comment.rs:35:13
|
LL | let x = /** comment */ 47;
| ^^^^^^^^^^^^^^ -- rustdoc does not generate documentation for expressions
+ |
+ = help: use `/* */` for a plain comment
error: unused doc comment
--> $DIR/useless-comment.rs:37:5
LL | |
LL | | }
| |_____- rustdoc does not generate documentation for expressions
+ |
+ = help: use `//` for a plain comment
error: aborting due to 10 previous errors