improve doc attr span tracking for proc-macro by andogq · Pull Request #17678 · rust-lang/rust-clippy

andogq · 2026-09-03T05:10:33Z

Resolves #16317
Resolves #16382
Resolves #16713

Largely based on #16713.

Lint documentation is contained within doc-comments within a macro invocation. Therefore, any lints were not applied to them up until now. A separate commit addresses these problems.

changelog: [empty_docs]: lint user-provided doc on proc-macro expanded codes
changelog: [missing_safety_doc]: lint user-provided doc on proc-macro expanded codes
changelog: [missing_panics_doc]: lint user-provided doc on proc-macro expanded codes

rustbot · 2026-09-03T05:10:37Z

Some changes occurred in clippy_lints/src/doc

cc @notriddle

rustbot · 2026-09-03T05:10:37Z

Thanks for the pull request, and welcome!

You should hear from one of our reviewers after this PR gets at least 2 reviews from the community.

Please see the contribution instructions for more information.

github-actions · 2026-09-03T05:20:34Z

Lintcheck changes for 1b55172

Lint	Added	Removed	Changed
`clippy::doc_markdown`	8	13	5
`clippy::doc_paragraphs_missing_punctuation`	1	0	1
`clippy::too_long_first_doc_paragraph`	1	0	0

This comment will be updated if you push new changes

andogq · 2026-09-03T09:47:58Z

(follow on from #16713 (comment))

Only some of these item kinds produced the 'missing backticks' clippy::doc_markdown lint due to a very specific requirement in order to resolve a Span from a markdown string:

Since these doc comments are within a macro invocation, they are turned into DocFragmentKind::Raw

Before emitting the backtick lint on a word (eg. foreign_mod), it's span is resolved

This resolution is performed by source_span_for_markdown_range_inner (via Fragments), which cannot disambiguate between multiple instances of a match within a markdown block.

All that being said, I feel that properly backticking these item kinds is appropriate.

View changes since the review

CommanderStorm

Community review: LGTM.

Maybe the test coverage could be improved a bit, since it is currently only #[doc..] and not ///.
Though as you noted (is my understanding of ?), this is an false negative currently, so 🤷🏻‍♂️

View changes since this review

CommanderStorm · 2026-09-03T11:59:06Z

(also if you are nice, make sure to include an Resolves #16713 in the PR description, since I think closing also works with PRs)

andogq · 2026-09-03T12:51:55Z

make sure to include an Resolves #16713 in the PR description

Good idea, thanks!

test coverage could be improved

These issues occur when doc comments are in the #[doc = "..."] form. The existing test cases only handle /// ..., so these new test cases close that gap. If there's any specific tests you'd like to see however, I'd be happy to add them in.

CommanderStorm · 2026-09-03T14:36:38Z

These issues occur when doc comments are in the #[doc = "..."] form.

Yes, but adding test coverage for the other form would be nice to have too, even if just to confirm that we don't regress on this one. So the combination of external! and ///, everywhere where you added the combination of external! and #[doc..]

As I alured, this one is for bonus points and not something that is required 😉

rustbot · 2026-09-03T16:35:45Z

r? @blyxyas

rustbot has assigned @blyxyas for the project review.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: 9 candidates
9 candidates expanded to 9 candidates
Random selection from 6 candidates

rustbot · 2026-09-14T02:46:29Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

blyxyas · 2026-09-22T17:58:37Z

+            let (_, kind) = attr.doc_str_and_fragment_kind()?;
+            let (is_raw, doc_str_span) = match kind {
+                DocFragmentKind::Sugared(_) => (false, attr.span()),
+                DocFragmentKind::Raw(span) => (true, span),
+            };
+            let from_include_str_macro = is_raw
+                && !attr.span().in_external_macro(cx.sess().source_map())
+                && originated_from_include_str_macro(cx, doc_str_span);
+            (from_include_str_macro || !doc_str_span.in_external_macro(cx.sess().source_map())).then_some((attr, None))


Much better! ❤️

View changes since the review

blyxyas

LGTM, thanks for addressing this issue! ❤️ ฅ•ω•ฅ

Could you squash these commits?

View changes since this review

andogq · 2026-09-23T00:24:58Z

@blyxyas Thank you for the review! Commits have been squashed, let me know if there's anything else that's needed.

rustbot added the S-waiting-on-community-reviews Status: This is awaiting for positive reviews from the community before a maintainer is assigned. label Sep 3, 2026

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties label Sep 3, 2026

This comment has been minimized.

Sign in to view

andogq force-pushed the fix/doc-attr-checks branch from 0fcb239 to ff99bf7 Compare September 3, 2026 05:11

andogq force-pushed the fix/doc-attr-checks branch from ff99bf7 to a14ea79 Compare September 3, 2026 09:35

andogq commented Sep 3, 2026

View reviewed changes

andogq force-pushed the fix/doc-attr-checks branch from a14ea79 to 02eac0e Compare September 3, 2026 09:56

CommanderStorm approved these changes Sep 3, 2026

View reviewed changes

notriddle approved these changes Sep 3, 2026

View reviewed changes

rustbot removed the S-waiting-on-community-reviews Status: This is awaiting for positive reviews from the community before a maintainer is assigned. label Sep 3, 2026

rustbot assigned blyxyas Sep 3, 2026

andogq mentioned this pull request Sep 4, 2026

Enable cargo clippy and cargo check in precommit hooks canonical/mir#5199

Merged

3 tasks

blyxyas mentioned this pull request Sep 7, 2026

use more robust doc attr span checking for proc-macro #16713

Closed

This comment has been minimized.

Sign in to view

andogq force-pushed the fix/doc-attr-checks branch from 02eac0e to 6302650 Compare September 14, 2026 02:46

blyxyas reviewed Sep 14, 2026

View reviewed changes

Comment thread clippy_lints/src/bool_to_int_with_if.rs Outdated

Comment thread clippy_lints/src/doc/mod.rs Outdated

Comment thread clippy_lints/src/doc/mod.rs Outdated

andogq force-pushed the fix/doc-attr-checks branch from 6302650 to 17964ca Compare September 22, 2026 02:17

andogq requested a review from blyxyas September 22, 2026 04:34

blyxyas reviewed Sep 22, 2026

View reviewed changes

blyxyas approved these changes Sep 22, 2026

View reviewed changes

improve doc attr span tracking for proc-macro

1b55172

andogq force-pushed the fix/doc-attr-checks branch from 17964ca to 1b55172 Compare September 23, 2026 00:14

blyxyas added this pull request to the merge queue Sep 23, 2026

Merged via the queue into rust-lang:master with commit a083651 Sep 23, 2026
13 checks passed

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties label Sep 23, 2026

andogq deleted the fix/doc-attr-checks branch September 24, 2026 01:18

This was referenced Oct 23, 2026

#[component] prop docs fail clippy's doc_markdown since nightly-2026-10-02 leptos-rs/leptos#4963

Closed

doc_markdown lints generated doc text when a proc macro gives it a user span #17911

Open

Conversation

andogq commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Sep 3, 2026

Uh oh!

rustbot commented Sep 3, 2026

Uh oh!

This comment has been minimized.

github-actions Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andogq Sep 3, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CommanderStorm 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!

CommanderStorm commented Sep 3, 2026

Uh oh!

andogq commented Sep 3, 2026

Uh oh!

CommanderStorm commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Sep 3, 2026

Uh oh!

This comment has been minimized.

rustbot commented Sep 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blyxyas Sep 22, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blyxyas 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!

andogq commented Sep 23, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

andogq commented Sep 3, 2026 •

edited

Loading

github-actions Bot commented Sep 3, 2026 •

edited

Loading

andogq Sep 3, 2026 •

edited by rustbot

Loading

CommanderStorm left a comment •

edited

Loading

CommanderStorm commented Sep 3, 2026 •

edited

Loading

blyxyas Sep 22, 2026 •

edited by rustbot

Loading

blyxyas left a comment •

edited

Loading