clean things up

src/librustc_expand/expand.rs

@@ -14,6 +14,7 @@ use rustc_parse::configure;
 use rustc_parse::parser::Parser;
 use rustc_parse::validate_attr;
 use rustc_parse::DirectoryOwnership;
+use rustc_session::lint::BuiltinLintDiagnostics;
 use rustc_session::lint::builtin::UNUSED_DOC_COMMENTS;
 use rustc_session::parse::{feature_err, ParseSess};
 use rustc_span::source_map::respan;
@@ -1093,7 +1094,12 @@ impl<'a, 'b> InvocationCollector<'a, 'b> {
             }
 
             if attr.doc_str().is_some() {
-                self.cx.parse_sess.buffer_lint(&UNUSED_DOC_COMMENTS, attr.span, ast::CRATE_NODE_ID, "yep, it's unused");
+                self.cx.parse_sess.buffer_lint_with_diagnostic(
+                    &UNUSED_DOC_COMMENTS,
+                    attr.span,
+                    ast::CRATE_NODE_ID,
+                    "unused doc comment",
+                    BuiltinLintDiagnostics::UnusedDocComment(attr.span));
             }
         }
     }

src/librustc_lint/builtin.rs

@@ -744,7 +744,6 @@ trait UnusedDocCommentExt {
         cx: &EarlyContext<'_>,
         node_span: Span,
         node_kind: &str,
-        is_macro_expansion: bool,
         attrs: &[ast::Attribute],
     );
 }
@@ -755,7 +754,6 @@ impl UnusedDocCommentExt for UnusedDocComment {
         cx: &EarlyContext<'_>,
         node_span: Span,
         node_kind: &str,
-        is_macro_expansion: bool,
         attrs: &[ast::Attribute],
     ) {
         let mut attrs = attrs.into_iter().peekable();
@@ -783,12 +781,6 @@ impl UnusedDocCommentExt for UnusedDocComment {
                         node_span,
                         format!("rustdoc does not generate documentation for {}", node_kind),
                     );
-                    if is_macro_expansion {
-                        err.help(
-                            "to document an item produced by a macro, \
-                                  the macro must produce the documentation as part of its expansion",
-                        );
-                    }
                     err.emit();
                 });
             }
@@ -797,31 +789,24 @@ impl UnusedDocCommentExt for UnusedDocComment {
 }
 
 impl EarlyLintPass for UnusedDocComment {
-    fn check_item(&mut self, cx: &EarlyContext<'_>, item: &ast::Item) {
-        if let ast::ItemKind::Mac(..) = item.kind {
-            self.warn_if_doc(cx, item.span, "macro expansions", true, &item.attrs);
-        }
-    }
-
     fn check_stmt(&mut self, cx: &EarlyContext<'_>, stmt: &ast::Stmt) {
-        let (kind, is_macro_expansion) = match stmt.kind {
-            ast::StmtKind::Local(..) => ("statements", false),
-            ast::StmtKind::Item(..) => ("inner items", false),
-            ast::StmtKind::Mac(..) => ("macro expansions", true),
+        let kind = match stmt.kind {
+            ast::StmtKind::Local(..) => "statements",
+            ast::StmtKind::Item(..) => "inner items",
             // expressions will be reported by `check_expr`.
-            ast::StmtKind::Semi(..) | ast::StmtKind::Expr(..) => return,
+            ast::StmtKind::Semi(..) | ast::StmtKind::Expr(..) | ast::StmtKind::Mac(..) => return,
         };
 
-        self.warn_if_doc(cx, stmt.span, kind, is_macro_expansion, stmt.kind.attrs());
+        self.warn_if_doc(cx, stmt.span, kind, stmt.kind.attrs());
     }
 
     fn check_arm(&mut self, cx: &EarlyContext<'_>, arm: &ast::Arm) {
         let arm_span = arm.pat.span.with_hi(arm.body.span.hi());
-        self.warn_if_doc(cx, arm_span, "match arms", false, &arm.attrs);
+        self.warn_if_doc(cx, arm_span, "match arms", &arm.attrs);
     }
 
     fn check_expr(&mut self, cx: &EarlyContext<'_>, expr: &ast::Expr) {
-        self.warn_if_doc(cx, expr.span, "expressions", false, &expr.attrs);
+        self.warn_if_doc(cx, expr.span, "expressions", &expr.attrs);
     }
 }
 

src/librustc_lint/context.rs

@@ -565,6 +565,11 @@ pub trait LintContext: Sized {
                 BuiltinLintDiagnostics::DeprecatedMacro(suggestion, span) => {
                     stability::deprecation_suggestion(&mut db, suggestion, span)
                 }
+                BuiltinLintDiagnostics::UnusedDocComment(span) => {
+                    db.span_label(span, "rustdoc does not generate documentation for macros");
+                    db.help("to document an item produced by a macro, \
+                                  the macro must produce the documentation as part of its expansion");
+                }
             }
             // Rewrap `db`, and pass control to the user.
             decorate(LintDiagnosticBuilder::new(db));

src/librustc_session/lint.rs

@@ -190,6 +190,7 @@ pub enum BuiltinLintDiagnostics {
     UnusedImports(String, Vec<(Span, String)>),
     RedundantImport(Vec<(Span, bool)>, Ident),
     DeprecatedMacro(Option<Symbol>, Span),
+    UnusedDocComment(Span),
 }
 
 /// Lints that are buffered up early on in the `Session` before the

src/librustc_session/parse.rs

@@ -176,6 +176,25 @@ impl ParseSess {
         });
     }
 
+    pub fn buffer_lint_with_diagnostic(
+        &self,
+        lint: &'static Lint,
+        span: impl Into<MultiSpan>,
+        node_id: NodeId,
+        msg: &str,
+        diagnostic: BuiltinLintDiagnostics,
+    ) {
+        self.buffered_lints.with_lock(|buffered_lints| {
+            buffered_lints.push(BufferedEarlyLint {
+                span: span.into(),
+                node_id,
+                msg: msg.into(),
+                lint_id: LintId::of(lint),
+                diagnostic,
+            });
+        });
+    }
+
     /// Extend an error with a suggestion to wrap an expression with parentheses to allow the
     /// parser to continue parsing the following operation as part of the same expression.
     pub fn expr_parentheses_needed(

src/test/ui/useless-comment.rs

@@ -6,7 +6,7 @@ macro_rules! mac {
     () => {}
 }
 
-/// foo //~ ERROR yep, it's unused
+/// foo //~ ERROR unused doc comment
 mac!();
 
 fn foo() {
@@ -29,7 +29,7 @@ fn foo() {
     #[doc = "bar"] //~ ERROR unused doc comment
     3;
 
-    /// bar //~ ERROR yep, it's unused
+    /// bar //~ ERROR unused doc comment
     mac!();
 
     let x = /** comment */ 47; //~ ERROR unused doc comment

src/test/ui/useless-comment.stderr

@@ -1,20 +1,23 @@
-error: yep, it's unused
+error: unused doc comment
   --> $DIR/useless-comment.rs:9:1
    |
 LL | /// foo
-   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ rustdoc does not generate documentation for macros
    |
 note: the lint level is defined here
   --> $DIR/useless-comment.rs:3:9
    |
 LL | #![deny(unused_doc_comments)]
    |         ^^^^^^^^^^^^^^^^^^^
+   = help: to document an item produced by a macro, the macro must produce the documentation as part of its expansion
 
-error: yep, it's unused
+error: unused doc comment
   --> $DIR/useless-comment.rs:32:5
    |
 LL |     /// bar
-   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ rustdoc does not generate documentation for macros
+   |
+   = help: to document an item produced by a macro, the macro must produce the documentation as part of its expansion
 
 error: unused doc comment
   --> $DIR/useless-comment.rs:13:5