Split non macro portion of unused_doc_comment from macro part into two passes/lints

[yaahc]

Motivation

This change is motivated by the needs of the spandoc library. The specific use case is that my macro is removing doc comments when an attribute is applied to a fn with doc comments, but I would like the lint to still appear when I forget to add the #[spandoc] attribute to a fn, so I don't want to have to silence the lint globally.

Approach

This change splits the unused _doc_comment lint into two lints, unused_macro_doc_comment and unused_doc_comment. The non macro portion is moved into an early_lint_pass rather than a pre_expansion_pass. This allows proc macros to silence unused_doc_comment warnings by either adding an attribute to silence it or by removing the doc comment before the early_pass runs.

The unused_macro_doc_comment lint however will still be impossible for proc-macros to silence, but the only alternative that I can see is to remove this lint entirely, which I don't think is acceptable / is a decision I'm not comfortable making personally, so instead I opted to split the macro portion of the check into a separate lint so that it can be silenced globally with an attribute if necessary without needing to globally silence the unused_doc_comment lint as well, which is still desireable.

fixes #67838

[rust-highfive]

r? @ecstatic-morse

(rust_highfive has picked a reviewer for you, use r? to override)

[Manishearth]

@bors r+

I was initially concerned that this would break doc comments for macros, but this is just a lint, it's fine. We should not be linting about pretty much anything pre-proc macros except for things which affect lexing, which is true for the other pre-proc-macro pass.

[bors]

📌 Commit 03863236992e376a87c6d5efb3961be11721d85a has been approved by Manishearth

[yaahc]

This does break a change made last year to improve diagnostics on macros

tree cabd6022a0ec9a157fdce48be26ddc408d626219
parent 018d4d265fb40ea4301da5dc339bff962a6faa57
author Andy Russell <arussell123@gmail.com> Thu Jan 24 15:49:03 2019 -0500
committer Andy Russell <arussell123@gmail.com> Fri Mar 8 12:39:50 2019 -0500

expand unused doc comment diagnostic

Report the diagnostic on macro expansions, and add a label indicating
why the comment is unused.

@@ -802,7 +802,14 @@ impl LintPass for UnusedDocComment {
 }
 
 impl UnusedDocComment {
-    fn warn_if_doc(&self, cx: &EarlyContext, attrs: &[ast::Attribute]) {
+    fn warn_if_doc(
+        &self,
+        cx: &EarlyContext<'_>,
+        node_span: Span,
+        node_kind: &str,
+        is_macro_expansion: bool,
+        attrs: &[ast::Attribute]
+    ) {
         let mut attrs = attrs.into_iter().peekable();
 
         // Accumulate a single span for sugared doc comments.
@@ -825,27 +832,51 @@ impl UnusedDocComment {
             let span = sugared_span.take().unwrap_or_else(|| attr.span);
 
             if attr.name() == "doc" {
-                cx.struct_span_lint(
-                    UNUSED_DOC_COMMENTS,
-                    span,
-                    "doc comment not used by rustdoc",
-                ).emit();
+                let mut err = cx.struct_span_lint(UNUSED_DOC_COMMENTS, span, "unused doc comment");
+
+                err.span_label(
+                    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();
             }
         }
     }
 }

I'd like to not break this if possible, is it possible for a lint to exist in two passes, I really only need the lint on items in fns to be done after expansion so I can strip out doc comments in fn bodies.

[Manishearth]

@yaahc write two passes instead, one that specifically looks for doc comments on macro expansions only. multiple passes are allowed to produce the same lint

@bors r-

[Manishearth]

@bors r+

[bors]

📌 Commit a89a791fd3f3665fc9a63f8b837fafe888d35e69 has been approved by Manishearth

[yaahc]

Actually, I think I need to disable the macro prepass lint for check_stmt. I think this will be okay because we probably dont have people commonly trying to declare items in macros as statements and document them at the same time...

[Manishearth]

@bors r- delegate+

[bors]

✌️ @yaahc can now approve this pull request

[yaahc]

So for my needs I would definitely prefer that doc comments on macro calls as statements are still handled in the early_pass so they can be silenced. I tried removing the stmt check in the pre_expansion pass lint with the hope that expr / stmt checks would catch the attributes on the post expansion version but the attributes seem to disappear and we no longer produce a lint on the macro call within the fn body, even if I changed the macro call to actually expand to an expr.

Could I get some help figuring out how to correctly lint for doc comments on macros as expressions from an early pass lint or decide which would be preferable between not linting in this case at all or linting on this but reporting the lint as unused_macro_doc_comment so that it can be silenced independently, either of which would be okay though not ideal solutions for my problem.

[yaahc]

I went ahead and implemented the version that exports the macro portion of the lint as a separately named lint, in addition to having it implemented as a separate lint pass internally. I figured this would be the most likely solution we'd end up needing.

If someone knows of a way to still appropriately lint on the attributes on macros after they've been expanded then I'm down to put in the work to swap the solution to that, but it looks like prior to this being moved to be a preexpansion pass lint the lint just straight up didn't trigger for macros, so my expectation is that attributes on macros are discarded after expansion, and that this is the only way to preserve the lint but while not requiring a blanket allow on all unused doc comments to silence the macro lint warnings.

[Manishearth]

@bors r+

[bors]

📌 Commit df6eb29fa0d4003bd0ec2bbf7ef55e4cfb9e5d5c has been approved by Manishearth

[petrochenkov]

@bors rollup=never
(I'd like to review this.)

[yaahc]

@bors r+

[bors]

📌 Commit 09bc5e3 has been approved by yaahc

[bors]

⌛ Testing commit 09bc5e3 with merge ca07a23...

[bors]

💔 Test failed - checks-azure

[petrochenkov]

@yaahc
Meta: the convention is to @bors r=petrochenkov on behalf of the reviewer instead of @bors r+ing on behalf of yourself.

The CI failure looks spurious.
@bors r-

[petrochenkov]

@bors r+

[bors]

💡 This pull request was already approved, no need to approve it again.

• This pull request previously failed. You should add more commits to fix the bug, or use retry to trigger a build again.
• There's another pull request that is currently being tested, blocking this pull request: perf: Only process changed obligations in ObligationForest #69218

[bors]

📌 Commit 09bc5e3 has been approved by petrochenkov

[bors]

⌛ Testing commit 09bc5e3 with merge 0cbf1a602ead3e16296c5a43ab78ec5044e309f3...

[rust-highfive]

Your PR failed (pretty log, raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[bors]

💔 Test failed - checks-azure

[petrochenkov]

@bors retry

[bors]

⌛ Testing commit 09bc5e3 with merge b1f395d...

[bors]

☀️ Test successful - checks-azure
Approved by: petrochenkov
Pushing b1f395d to master...