use more robust doc attr span checking for proc-macro by zihan0822 · Pull Request #16713 · rust-lang/rust-clippy

zihan0822 · 2026-03-13T18:14:14Z

When checking the span of doc attributes, we use the span of the lit str instead of the span of hir::Attribute. This makes the span checking more robust when we are dealing with certain proc-macro crates.

For example, cxx's bridge takes doc lit str from user and attach them to a new #[doc] created by the proc-macro. In such case, checking the span of lit str makes sure that doc related lints can still fire properly on user-provided docs.

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-03-13T18:14:18Z

Some changes occurred in clippy_lints/src/doc

cc @notriddle

rustbot · 2026-03-13T18:14:21Z

r? @samueltardieu

rustbot has assigned @samueltardieu.
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: 7 candidates
7 candidates expanded to 7 candidates
Random selection from Jarcho, dswij, llogiq, samueltardieu

github-actions · 2026-03-13T18:23:51Z

Lintcheck changes for f0c1cb6

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

zihan0822 · 2026-03-14T08:44:15Z

dogfood output in ci makes sense to me.

@rustbot ready

samueltardieu · 2026-03-17T10:34:40Z

dogfood output in ci makes sense to me.

What do you mean? If you mean that some other Clippy sources need to be fixed, by all means do that in a separate commit that you would then move before the current one, so that at any point the CI would be green. Moreover that will show us some real-life consequences of those changes.

@rustbot author

rustbot · 2026-03-17T10:35:22Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

zihan0822 · 2026-03-17T13:11:05Z

fixed clippy source in a separate commit.

@rustbot ready

samueltardieu · 2026-03-26T17:08:18Z

    /// /// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
    /// /// [SmallVec]: SmallVec
-    /// fn main() {}
+    /// fn foo() {}


Why the rename here?

fn main() triggers clippy::needless_doctest_main

samueltardieu · 2026-03-26T17:11:34Z

-    ///     let a = 0123;
-    ///     println!("{}", a);
-    /// }
+    /// let a = 0123;


Why did you remove fn main()? Is that some cleanup or the result of applying the lint?

fn main() in rust listing triggers clippy::needless_doctest_main, main() in C was removed to pair with that.

samueltardieu · 2026-03-26T17:12:55Z

    /// | Group              | Item Kinds           |
    /// |--------------------|----------------------|
-    /// | `modules`          | "mod", "foreign_mod" |
+    /// | `modules`          | "mod", "foreign mod" |


Why did you remove the underscores? I'm not saying this is wrong, I'd like to understand this.

Snake-cased word is treated as item in markdown and it triggers clippy::doc_markdown with warning "item in documentation is missing backticks".

I actually don't know what we should do about this. I think it might be better to keep those words as snake-cased, since they seem to be used as keywords in clippy::arbitrary_source_item_ordering's config. There is no way to suppress this lint locally, because declare_clippy_lint! only accepts doc attribute. Can we just add backticks to all the words in Item Kinds column or add those words to clippy's allowed markdown idents?

clippy source Signed-off-by: Zihan <zihanli0822@gmail.com>

When checking the span of doc attributes, we use the span of the lit str instead of the span of `hir::Attribute`. This makes the span checking more robust when we are dealing with certain proc-macro crates. For example, some proc-macro crates may take doc lit str from user and attach them to a new `#[doc]` created by the proc-macro. In such cases, checking the span of lit str makes sure that doc related lints can still fire properly on user-provided docs. 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 changelog: [`needless_doctest_main`]: lint user-provided doc on proc-macro expanded codes changelog: [`doc_markdown`]: lint user-provided doc on proc-macro expanded codes Signed-off-by: Zihan <zihanli0822@gmail.com>

zihan0822 · 2026-03-27T06:36:56Z

    /// | `global_asm`       | "global_asm"         |
    /// | `UPPER_SNAKE_CASE` | "static", "const"    |
-    /// | `PascalCase`       | "ty_alias", "opaque_ty", "enum", "struct", "union", "trait", "trait_alias", "impl" |
+    /// | `PascalCase`       | "ty alias", "opaque ty", "enum", "struct", "union", "trait", "trait alias", "impl" |


It turns out that "foreign_mod" and "global_asm" do not trigger missing backticks, but all other snake-cased words in the table do. "foreign_mod" and "global_asm" actually have not been whitelisted as valid markdown idents in clippy config. I guess there might be some issue with clippy::doc_markdown lint.

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

rustbot assigned samueltardieu Mar 13, 2026

zihan0822 marked this pull request as draft March 13, 2026 18:27

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

zihan0822 force-pushed the fix-doc-header-span-check branch 2 times, most recently from 84e7d0a to 3d1dce6 Compare March 14, 2026 08:28

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

zihan0822 marked this pull request as ready for review March 14, 2026 08:44

rustbot added S-waiting-on-author Status: This is awaiting some action from the author. (Use `@rustbot ready` to update this status) and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties labels Mar 17, 2026

zihan0822 force-pushed the fix-doc-header-span-check branch from 3d1dce6 to d5ffe16 Compare March 17, 2026 13:00

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties and removed S-waiting-on-author Status: This is awaiting some action from the author. (Use `@rustbot ready` to update this status) labels Mar 17, 2026

notriddle suggested changes Mar 26, 2026

View reviewed changes

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

Comment thread clippy_lints/src/doc/mod.rs

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

zihan0822 force-pushed the fix-doc-header-span-check branch 3 times, most recently from c8c6833 to b7034e0 Compare March 26, 2026 05:41

zihan0822 requested a review from notriddle March 26, 2026 09:38

notriddle approved these changes Mar 26, 2026

View reviewed changes

samueltardieu requested changes Mar 26, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action from the author. (Use `@rustbot ready` to update this status) and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties labels Mar 26, 2026

fix up doc related lints for proc-macro expanded doc attributes in

577ee15

clippy source Signed-off-by: Zihan <zihanli0822@gmail.com>

zihan0822 force-pushed the fix-doc-header-span-check branch from b7034e0 to f0c1cb6 Compare March 27, 2026 06:19

zihan0822 commented Mar 27, 2026

View reviewed changes

Conversation

zihan0822 commented Mar 13, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Mar 13, 2026

Uh oh!

rustbot commented Mar 13, 2026

Uh oh!

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

Uh oh!

Uh oh!

zihan0822 commented Mar 14, 2026

Uh oh!

samueltardieu commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Mar 17, 2026

Uh oh!

zihan0822 commented Mar 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samueltardieu Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

zihan0822 Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

samueltardieu Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

zihan0822 Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samueltardieu Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

zihan0822 Mar 27, 2026 • 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!

Uh oh!

zihan0822 Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zihan0822 commented Mar 13, 2026 •

edited by rustbot

Loading

github-actions Bot commented Mar 13, 2026 •

edited

Loading

samueltardieu commented Mar 17, 2026 •

edited

Loading

zihan0822 Mar 27, 2026 •

edited

Loading