Add a help message to unused_doc_comments lint

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