[rustdoc] Do not emit redundant_explicit_links lint if the doc comment comes from expansion #141648

GuillaumeGomez · 2025-05-27T13:19:08Z

The problem was that we change the context for the attributes in some cases to get better error output, preventing us to detect if the attribute comes from expansion. Most of the changes are about keeping track of the "does this span comes from expansion" information.

r? @Manishearth

rustbot · 2025-05-27T14:16:28Z

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

lolbinarycat

Mostly nits about comments, but a few concerns about the actual logic as well.

compiler/rustc_resolve/src/rustdoc.rs

src/librustdoc/passes/lint/redundant_explicit_links.rs

tests/rustdoc-ui/lints/redundant_explicit_links-expansion.rs

bors · 2025-06-01T22:38:13Z

☔ The latest upstream changes (presumably #141869) made this pull request unmergeable. Please resolve the merge conflicts.

Manishearth · 2025-06-02T07:11:12Z

(I've been rather busy catching up with stuff after vacation; I probably won't be able to review this myself soon ,sorry!)

GuillaumeGomez · 2025-06-03T21:01:20Z

No worries, take your time. We can pick another reviewer in the meantime.

r? notriddle

GuillaumeGomez · 2025-06-10T14:25:59Z

Applied suggestions and added more tests.

lolbinarycat

There's 1 edge case I think this doesn't handle 100% correctly, and other than that I just have a few nits about wording, 1 tiny inefficiency, and some comments about how some control flow could be rewritten to use pattern matching (if we wanted that)

lolbinarycat · 2025-06-10T19:58:41Z

compiler/rustc_resolve/src/rustdoc.rs

        if let Some((doc_str, comment_kind)) = attr.doc_str_and_comment_kind() {
            let doc = beautify_doc_string(doc_str, comment_kind);
-            let (span, kind) = if attr.is_doc_comment() {
-                (attr.span(), DocFragmentKind::SugaredDoc)
+            let (span, kind, from_expansion) = if attr.is_doc_comment() {
+                let span = attr.span();
+                (span, DocFragmentKind::SugaredDoc, span.from_expansion())


This is actually a bit odd to me, doc_str_and_comment_kind knows if a doc fragment is raw or a comment, but it then we throw that info away only to recalculate it immediately. These functions probably get inlined and probably llvm de-duplicates the match, but it's still a bit messy, especially considering this is the only call site of doc_str_and_comment_kind besides 1 place in clippy that only checks if the return value is None.

compiler/rustc_resolve/src/rustdoc.rs

lolbinarycat · 2025-06-10T20:15:36Z

compiler/rustc_resolve/src/rustdoc.rs

-    Some(start.to(end))
+    Some((
+        first_fragment.span.to(last_fragment.span),
+        fragments.iter().any(|frag| frag.from_expansion),


This probably produces false negatives if all of the following are true:

there is a macro that produces sugared doc comments

there is a non-macro generated sugared doc comment containing a redundant explicit link

there are no raw doc fragments on the item

This may be an acceptable regression, but I thought it was worth noting.

This could perhaps be made even more unlikely by trying to use the unambiguous substring heuristic first, or it could be eliminated completely by first calculating the final source span, then only checking the from_expansion of fragments that overlap with that source span.

I suggest opening an issue once this PR is merged and send a PR with a regression test case. :)

Ah you propose a solution below, copying it then.

lolbinarycat · 2025-06-10T20:21:07Z

compiler/rustc_resolve/src/rustdoc.rs

+    Some((
+        span.from_inner(InnerSpan::new(
+            md_range.start + start_bytes,
+            md_range.end + start_bytes + end_bytes,
+        )),
+        from_expansion,


If we wanted to avoid the false negative I pointed out before, something like this could work:

Suggested change

Some((

span.from_inner(InnerSpan::new(

md_range.start + start_bytes,

md_range.end + start_bytes + end_bytes,

)),

from_expansion,

let src_span = span.from_inner(InnerSpan::new(

md_range.start + start_bytes,

md_range.end + start_bytes + end_bytes,

));

Some((

src_span,

fragments.iter().any(|frag| frag.span.overlaps(src_span) && frag.from_expansion),

src/librustdoc/passes/lint/redundant_explicit_links.rs

lolbinarycat · 2025-06-10T20:33:00Z

src/librustdoc/passes/lint/redundant_explicit_links.rs

+        let (display_span, from_expansion) = source_span_for_markdown_range(
            cx.tcx,
            doc,
            resolvable_link_range,
            &item.attrs.doc_strings,
        )?;
+        if from_expansion {
+            return None;
+        }


Comment: Technically this type of control flow could be expressed more tersely as let (foo, false) ... else { return None }; but that might not be the most readable thing.

In this case I think the let else is acceptable since we already know what the first element of the tuple is. I'm gonna implement this one then!

lolbinarycat · 2025-06-10T20:38:21Z

tests/rustdoc-ui/lints/redundant_explicit_links-expansion.rs

+#[doc = mac3!()]
+/// a [`BufferProvider`](crate::BufferProvider).
+//~^ ERROR: redundant_explicit_links
+pub fn f() {}


I kinda would like to see some tests exercising the all-sugared doc fragment case, where half of the fragments are macro-generated and half aren't. Ideally there would be two cases for this, one where the redundant link is in the macro generated fragment and thus the lint is suppressed, and one where the redundant link is in the non-macro generated fragment and thus the link is emitted.

…t comes from expansion

…ing from expansion

…it_links` new API

notriddle · 2025-06-13T15:31:34Z

I understand that this bail-out is needed because, in the event of a false positive, disabling the lint in the macro is impossible. There's nowhere to attach the attribute.

In that case, would it be simpler and make more sense to disable all of the markdown lints, and not just this one?

lolbinarycat

we can revert span_for_fragments
more places could use if/else

lolbinarycat · 2025-06-15T16:33:45Z

compiler/rustc_resolve/src/rustdoc.rs

@@ -659,8 +681,13 @@ pub fn source_span_for_markdown_range_inner(
        }
    }

-    Some(span_of_fragments(fragments)?.from_inner(InnerSpan::new(
+    let (span, _) = span_of_fragments_with_expansion(fragments)?;


We can revert span_of_fragments_with_expansion to just be span_of_fragments again now, right?

any future potential users of it would probably be suspect to the same edge case as is present here, and having a useless iteration isn't ideal.

lolbinarycat · 2025-06-15T16:49:59Z

src/librustdoc/passes/lint/redundant_explicit_links.rs

+                }
+                None => item.attr_span(cx.tcx),
+            };
+        let (explicit_span, from_expansion) = source_span_for_markdown_range(


this could also be let else

lolbinarycat · 2025-06-15T16:51:53Z

src/librustdoc/passes/lint/redundant_explicit_links.rs

+        if from_expansion {
+            return None;
+        }
+        let (display_span, from_expansion) = source_span_for_markdown_range(


this could also also be let else

rustbot assigned Manishearth May 27, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels May 27, 2025

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the redundant_explicit_links-expansion branch from 5e8b79b to ec9530a Compare May 27, 2025 13:53

This comment has been minimized.

Sign in to view

lolbinarycat reviewed May 27, 2025

View reviewed changes

GuillaumeGomez force-pushed the redundant_explicit_links-expansion branch from b486863 to 9ac0d61 Compare June 3, 2025 20:12

This comment has been minimized.

Sign in to view

rustbot assigned notriddle and unassigned Manishearth Jun 3, 2025

GuillaumeGomez force-pushed the redundant_explicit_links-expansion branch from 0ada37b to 8bcc067 Compare June 10, 2025 12:45

lolbinarycat reviewed Jun 10, 2025

View reviewed changes

GuillaumeGomez added 5 commits June 13, 2025 16:22

Do not emit redundant_explicit_links rustdoc lint if the doc commen…

84de541

…t comes from expansion

Add ui test for redundant_explicit_links rustdoc lint for items com…

258377c

…ing from expansion

Update clippy source code to changes on source_span_for_markdown_range

74b75a7

Update tests to work with new DocFragment field and `redundant_explic…

54b443c

…it_links` new API

Improve code and documentation

8c7779b

GuillaumeGomez force-pushed the redundant_explicit_links-expansion branch from 8bcc067 to 8c7779b Compare June 13, 2025 14:47

lolbinarycat reviewed Jun 15, 2025

View reviewed changes

[rustdoc] Do not emit redundant_explicit_links lint if the doc comment comes from expansion #141648

Are you sure you want to change the base?

[rustdoc] Do not emit redundant_explicit_links lint if the doc comment comes from expansion #141648

Uh oh!

Conversation

GuillaumeGomez commented May 27, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

rustbot commented May 27, 2025

Uh oh!

This comment has been minimized.

lolbinarycat left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bors commented Jun 1, 2025

Uh oh!

Manishearth commented Jun 2, 2025

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 3, 2025

Uh oh!

GuillaumeGomez commented Jun 10, 2025

Uh oh!

lolbinarycat left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

notriddle commented Jun 13, 2025

Uh oh!

lolbinarycat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lolbinarycat left a comment •

edited

Loading