Rollup merge of #86813 - JohnTitor:unused-doc-comments-help, r=jackh726

Add a help message to `unused_doc_comments` lint

Fixes #83492
This adds a help message to suggest a plain comment like the E0658 error. I've yet to come up with the best message about the doc attribute but the current shouldn't harm anything.
I was thinking of recovering in the `doc_comment_between_if_else` case, but I came to the conclusion that it unlikely happened and was an overkill.

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<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())));
         }
@@ -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();
             });
         }

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() {}

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 <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`.

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