From 086eb4764a67ecb874274f712a6576bd4a273fd0 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Sat, 3 Jul 2021 01:00:08 +0900 Subject: [PATCH] Add a help message to `unused_doc_comments` lint --- compiler/rustc_lint/src/builtin.rs | 15 ++++- .../unused/unused-doc-comments-edge-cases.rs | 29 +++++++++ .../unused-doc-comments-edge-cases.stderr | 61 +++++++++++++++++++ src/test/ui/unused/useless-comment.stderr | 16 +++++ 4 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 src/test/ui/unused/unused-doc-comments-edge-cases.rs create mode 100644 src/test/ui/unused/unused-doc-comments-edge-cases.stderr diff --git a/compiler/rustc_lint/src/builtin.rs b/compiler/rustc_lint/src/builtin.rs index 65695fc03de..b303f55cf77 100644 --- a/compiler/rustc_lint/src/builtin.rs +++ b/compiler/rustc_lint/src/builtin.rs @@ -984,13 +984,16 @@ impl EarlyLintPass for DeprecatedAttr { } 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 = 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()))); } @@ -1001,13 +1004,21 @@ fn warn_if_doc(cx: &EarlyContext<'_>, node_span: Span, node_kind: &str, attrs: & 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(); }); } diff --git a/src/test/ui/unused/unused-doc-comments-edge-cases.rs b/src/test/ui/unused/unused-doc-comments-edge-cases.rs new file mode 100644 index 00000000000..fd9baf8c6b9 --- /dev/null +++ b/src/test/ui/unused/unused-doc-comments-edge-cases.rs @@ -0,0 +1,29 @@ +#![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() {} diff --git a/src/test/ui/unused/unused-doc-comments-edge-cases.stderr b/src/test/ui/unused/unused-doc-comments-edge-cases.stderr new file mode 100644 index 00000000000..14db5f64b0c --- /dev/null +++ b/src/test/ui/unused/unused-doc-comments-edge-cases.stderr @@ -0,0 +1,61 @@ +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 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`. diff --git a/src/test/ui/unused/useless-comment.stderr b/src/test/ui/unused/useless-comment.stderr index 5a0af8db7c5..0054426fb1e 100644 --- a/src/test/ui/unused/useless-comment.stderr +++ b/src/test/ui/unused/useless-comment.stderr @@ -26,6 +26,8 @@ LL | /// a | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 @@ -40,6 +42,8 @@ LL | | 1 => {}, 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 @@ -48,6 +52,8 @@ LL | /// c | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 @@ -56,6 +62,8 @@ LL | /// foo | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 @@ -65,6 +73,8 @@ LL | #[doc = "foo"] 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 @@ -73,12 +83,16 @@ 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: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 @@ -89,6 +103,8 @@ LL | / { LL | | LL | | } | |_____- rustdoc does not generate documentation for expressions + | + = help: use `//` for a plain comment error: aborting due to 10 previous errors