Fix `doc_cfg` not working as expected on trait impls by GuillaumeGomez · Pull Request #153964 · rust-lang/rust

GuillaumeGomez · 2026-03-16T16:27:54Z

I spent waaaaay too much time on this fix. So the current issue is that rustdoc gets its items in two passes:

All items
Trait/blanket/auto impls

Because of that, the trait impls are not stored "correctly" in the rustdoc AST, meaning that the propagate_doc_cfg pass doesn't work correctly on them. So initially, I tried to "clean" the impls at the same time as the other items. However, it created a monstruous amount of bugs and issues and after two days, I decided to give up on this approach (might be worth fixing that in the future!). You can see what I tried here.

So instead, since the impls are stored at the end, I create placeholders for impls and in propagate_doc_cfg, I store the cfg "context" (more clear when reading the code 😛) and re-use it later on when the "real" impl comes up.

r? @lolbinarycat

GuillaumeGomez · 2026-03-16T19:45:38Z

Not great that ImplItem and PlaceholderImplItem need to be handled in rustdoc lints. :-/

GuillaumeGomez · 2026-03-16T21:02:38Z

And CI passed. \o/

lolbinarycat

Code looks good to me but I still need to do a more in-depth investigation of the logic. For now, here's some nits and clarifying questions.

View changes since this review

lolbinarycat · 2026-03-17T05:30:06Z

src/librustdoc/clean/mod.rs

    impl_: &hir::Impl<'tcx>,
    def_id: LocalDefId,
    cx: &mut DocContext<'tcx>,
+    // If `renamed` is some, then this is an inlined impl and it will be handled later on in the


nit: ambiguous pronoun, this would be less ambiguous if "this" was replaced with an actual name.

src/librustdoc/json/conversions.rs

src/librustdoc/passes/calculate_doc_coverage.rs

lolbinarycat · 2026-03-17T05:35:46Z

src/librustdoc/passes/stripper.rs


            clean::ImplItem(..) => {}

+            // They have no use anymore, so always remove them.


nit: great comments explain why code does something.

lolbinarycat · 2026-03-17T05:38:36Z

tests/rustdoc-html/doc-cfg/trait-impls.rs

@@ -0,0 +1,59 @@
+// This test ensures that `doc_cfg` feature is working as expected on trait impls.


just to be sure: we do have a test for non-trait impls, right? we definitely don't want to regress that.

also, do we have a test for non-auto doc(cfg(...)) on trait items?

Doesn't hurt to add one in the same test I guess. Gonna add a test for non-auto doc(cfg(...)) too.

src/librustdoc/clean/mod.rs

GuillaumeGomez · 2026-03-17T11:47:55Z

Added comments and greatly extended the tests.

GuillaumeGomez · 2026-03-17T13:20:53Z

Seems like a flaky failure. Restarted CI.

lolbinarycat

I took a closer look at the actual logic this time and it seems solid and straightforwards, I can't come up with any edge cases that it would cause problems in.

My only issue of immediate relevance is rustc_span::symbol::kw::Impl and renamed being used in a somewhat unintuitive way, not sure what the best way to address that is but it definitely has an impact on code readability. I also found some missing test coverage but that's mostly unrelated so that can be handled in a followup PR if you want.

View changes since this review

src/librustdoc/passes/check_doc_test_visibility.rs

src/librustdoc/passes/calculate_doc_coverage.rs

src/librustdoc/passes/propagate_doc_cfg.rs

src/librustdoc/visit_ast.rs

GuillaumeGomez · 2026-03-18T15:49:24Z

I added code comments to explain that the symbol is used as a sentinel value.

fmease · 2026-03-18T17:04:32Z

src/librustdoc/visit_ast.rs

+                    if impl_.of_trait.is_none() {
+                        None
+                    } else {
+                        Some(rustc_span::symbol::kw::Impl)
+                    },


Would replacing parameter type Option<Symbol> with Option<BikeshedTy> be possible / much of a hassle where BikeshedTy is a new type that could be defined like enum BikeshedTy { BikeshedName(Symbol), BikeshedAnon }? I haven't read the rest of the diff, lol

Context: this argument is what an inlined item is renamed into. So no, I don't want to rename it. 😝

@lolbinarycat

…amples-improvement, r=lolbinarycat Don't emit rustdoc `missing_doc_code_examples` lint on impl items @lolbinarycat realized in [this comment](rust-lang#153964 (comment)) that we weren't testing some cases for the `missing_doc_code_examples` lint. Turns out that it was not handling this case well. =D So in short: `missing_doc_code_examples` lint should not be emitted on impl items and this PR fixes that. r? @lolbinarycat

@lolbinarycat

…amples-improvement, r=lolbinarycat Don't emit rustdoc `missing_doc_code_examples` lint on impl items @lolbinarycat realized in [this comment](rust-lang#153964 (comment)) that we weren't testing some cases for the `missing_doc_code_examples` lint. Turns out that it was not handling this case well. =D So in short: `missing_doc_code_examples` lint should not be emitted on impl items and this PR fixes that. r? @lolbinarycat

@lolbinarycat

…amples-improvement, r=lolbinarycat Don't emit rustdoc `missing_doc_code_examples` lint on impl items @lolbinarycat realized in [this comment](rust-lang#153964 (comment)) that we weren't testing some cases for the `missing_doc_code_examples` lint. Turns out that it was not handling this case well. =D So in short: `missing_doc_code_examples` lint should not be emitted on impl items and this PR fixes that. r? @lolbinarycat

GuillaumeGomez · 2026-03-20T16:49:59Z

Fixed merge conflict.

lolbinarycat

One last review pass, two points of substance and two very tiny nits about word choice in comments.

View changes since this review

lolbinarycat · 2026-03-23T18:13:32Z

src/librustdoc/clean/mod.rs

+    // If `renamed` is some, then `impl_` is an inlined impl and it will be handled later on in the
+    // code. In here, we will generate a placeholder for it in order to be able to compute its
+    // `doc_cfg` info.
+    renamed: Option<Symbol>,


After some reflection I think this should probably just be a boolean parameter called something like is_inlined. I feel like too often rustdoc just passes variables along as function parameters with the same name, even when they don't really make sense in that context. Although why are we saying "inlined" and not "trait" here? Is there some subtle difference I'm missing?

If this item is renamed, we can probably remove the comment, but we'll definitely need to make sure that the comment in clean_maybe_renamed_item is updated to still make sense.

Fair enough.

lolbinarycat · 2026-03-23T18:15:57Z

src/librustdoc/passes/propagate_doc_cfg.rs

    cx: &'a mut DocContext<'tcx>,
    cfg_info: CfgInfo,
+
+    /// To ensure the `doc_cfg` feature works with how `rustdoc` handles impl, we need to store


Suggested change

/// To ensure the `doc_cfg` feature works with how `rustdoc` handles impl, we need to store

/// To ensure the `doc_cfg` feature works with how `rustdoc` handles impls, we need to store

nit: typo

lolbinarycat · 2026-03-23T18:19:08Z

src/librustdoc/passes/propagate_doc_cfg.rs

+        // If we have an impl, we check if it has an associated `cfg` "context", and if so we will
+        // use this context instead of the actual (wrong) one.


Suggested change

// If we have an impl, we check if it has an associated `cfg` "context", and if so we will

// use this context instead of the actual (wrong) one.

// If we have an impl, we check if it has an associated `cfg` "context", and if so we will

// use that context instead of the actual (wrong) one.

very minor and somewhat subjective nit

lolbinarycat · 2026-03-23T18:26:04Z

src/librustdoc/visit_ast.rs

                // them up regardless of where they're located.
-                if !self.inlining && impl_.of_trait.is_none() {
-                    self.add_to_current_mod(item, None, None);
+                if !self.inlining {


Instead of copy-pasting this code, I'd like to see it refactored into a utility method add_impl_to_current_mod.

rustbot · 2026-03-23T20:47:44Z

This PR was rebased onto a different main 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.

rustbot · 2026-03-23T20:47:45Z

⚠️ Warning ⚠️

There are issue links (such as #123) in the commit messages of the following commits.
Please move them to the PR description, to avoid spamming the issues with references to the commit, and so this bot can automatically canonicalize them to avoid issues with subtree.
- 73fe4c5

GuillaumeGomez · 2026-03-23T20:48:35Z

Applied all suggestions!

lolbinarycat · 2026-03-23T21:56:06Z

Thanks!

@bors r+

rust-bors · 2026-03-23T21:56:09Z

📌 Commit 19876d1 has been approved by lolbinarycat

It is now in the queue for this repository.

@lolbinarycat

…cfg, r=lolbinarycat Fix `doc_cfg` not working as expected on trait impls Fixes rust-lang#153655. I spent waaaaay too much time on this fix. So the current issue is that rustdoc gets its items in two passes: 1. All items 2. Trait/blanket/auto impls Because of that, the trait impls are not stored "correctly" in the rustdoc AST, meaning that the `propagate_doc_cfg` pass doesn't work correctly on them. So initially, I tried to "clean" the impls at the same time as the other items. However, it created a monstruous amount of bugs and issues and after two days, I decided to give up on this approach (might be worth fixing that in the future!). You can see what I tried [here](https://github.com/rust-lang/rust/compare/main...GuillaumeGomez:trait-impls-doc_cfg?expand=1). So instead, since the impls are stored at the end, I create placeholders for impls and in `propagate_doc_cfg`, I store the `cfg` "context" (more clear when reading the code 😛) and re-use it later on when the "real" impl comes up. r? @lolbinarycat

Rollup of 10 pull requests Successful merges: - #153964 (Fix `doc_cfg` not working as expected on trait impls) - #153979 (Rename various query cycle things.) - #154132 (Add missing num_internals feature gate to coretests/benches) - #154153 (core: Implement `unchecked_funnel_{shl,shr}`) - #154236 (Clean up query-forcing functions) - #154252 (Don't store current-session side effects in `OnDiskCache`) - #154017 ( Fix invalid add of duplicated call locations for the rustdoc scraped examples feature) - #154163 (enzyme submodule update) - #154264 (Update books) - #154282 (rustc-dev-guide subtree update)

@eggyal

…, r=eggyal,tgross35 [libcore] Disable `doc(auto_cfg)` for integers trait impls Fixes rust-lang#153655. Thanks to rust-lang#153964, `doc(auto_cfg)` finally works as expected on impls. So now this fix works: <img width="1000" height="806" alt="image" src="https://github.com/user-attachments/assets/f37da375-c2eb-4a7b-abf2-1fdd3a73e2bb" /> cc @eggyal

@eggyal

…, r=eggyal,tgross35 [libcore] Disable `doc(auto_cfg)` for integers trait impls Fixes rust-lang#153655. Thanks to rust-lang#153964, `doc(auto_cfg)` finally works as expected on impls. So now this fix works: <img width="1000" height="806" alt="image" src="https://github.com/user-attachments/assets/f37da375-c2eb-4a7b-abf2-1fdd3a73e2bb" /> cc @eggyal

rustbot assigned lolbinarycat Mar 16, 2026

This comment has been minimized.

Sign in to view

GuillaumeGomez changed the title ~~Fix trait impl doc cfg~~ Fix doc_cfg not working as expected on trait impls Mar 16, 2026

GuillaumeGomez mentioned this pull request Mar 16, 2026

rustdoc reports wrong config conditions for impl LowerExp for integers #153655

Closed

This comment has been minimized.

Sign in to view

lolbinarycat reviewed Mar 17, 2026

View reviewed changes

GuillaumeGomez force-pushed the fix-trait-impl-doc-cfg branch from ce71ac8 to 2dd7677 Compare March 17, 2026 11:47

This comment has been minimized.

Sign in to view

Darksonn mentioned this pull request Mar 18, 2026

chore: Do not show "Available on non-loom only." doc label tokio-rs/tokio#7977

Merged

lolbinarycat reviewed Mar 18, 2026

View reviewed changes

src/librustdoc/passes/check_doc_test_visibility.rs Show resolved Hide resolved

src/librustdoc/passes/calculate_doc_coverage.rs Show resolved Hide resolved

src/librustdoc/passes/propagate_doc_cfg.rs Show resolved Hide resolved

src/librustdoc/visit_ast.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the fix-trait-impl-doc-cfg branch from 2dd7677 to 3f0f7d7 Compare March 18, 2026 15:49

GuillaumeGomez mentioned this pull request Mar 18, 2026

Don't emit rustdoc missing_doc_code_examples lint on impl items #154048

Merged

fmease reviewed Mar 18, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the fix-trait-impl-doc-cfg branch from 3f0f7d7 to 2752dc5 Compare March 20, 2026 16:49

This comment has been minimized.

Sign in to view

lolbinarycat reviewed Mar 23, 2026

View reviewed changes

GuillaumeGomez and others added 5 commits March 23, 2026 21:25

Fix doc_cfg not working as expected on trait impls

953210c

Add regression test for rust-lang#153655

73fe4c5

Correctly handle rustdoc PlaceholderImplItem in lints

6fcd011

Add more comments to explain code

24e40f0

Simplify code and improve code comments

19876d1

GuillaumeGomez force-pushed the fix-trait-impl-doc-cfg branch from 2752dc5 to 19876d1 Compare March 23, 2026 20:47

rust-bors bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 23, 2026

JonathanBrouwer mentioned this pull request Mar 23, 2026

Rollup of 6 pull requests #154280

Closed

jhpratt mentioned this pull request Mar 24, 2026

Rollup of 10 pull requests #154289

Merged

rust-bors bot merged commit 8a2bd0f into rust-lang:main Mar 24, 2026
11 checks passed

rustbot added this to the 1.96.0 milestone Mar 24, 2026

GuillaumeGomez mentioned this pull request Mar 24, 2026

[libcore] Disable doc(auto_cfg) for integers trait impls #154311

Merged


		clean::ImplItem(..) => {}

		// They have no use anymore, so always remove them.

		@@ -0,0 +1,59 @@
		// This test ensures that `doc_cfg` feature is working as expected on trait impls.

	/// To ensure the `doc_cfg` feature works with how `rustdoc` handles impl, we need to store
	/// To ensure the `doc_cfg` feature works with how `rustdoc` handles impls, we need to store

		// If we have an impl, we check if it has an associated `cfg` "context", and if so we will
		// use this context instead of the actual (wrong) one.

Uh oh!

Conversation

GuillaumeGomez commented Mar 16, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Mar 16, 2026

Uh oh!

GuillaumeGomez commented Mar 16, 2026

Uh oh!

lolbinarycat left a comment • 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!

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!

GuillaumeGomez Mar 17, 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!

This comment has been minimized.

GuillaumeGomez commented Mar 17, 2026

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Mar 17, 2026

Uh oh!

lolbinarycat left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GuillaumeGomez commented Mar 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Mar 18, 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!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Mar 20, 2026

Uh oh!

lolbinarycat left a comment • 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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Mar 23, 2026

Uh oh!

rustbot commented Mar 23, 2026

Uh oh!

GuillaumeGomez commented Mar 23, 2026

Uh oh!

lolbinarycat commented Mar 23, 2026

Uh oh!

rust-bors bot commented Mar 23, 2026

Uh oh!

lolbinarycat left a comment •

edited by rustbot

Loading

GuillaumeGomez Mar 17, 2026 •

edited

Loading

lolbinarycat left a comment •

edited by rustbot

Loading

GuillaumeGomez Mar 18, 2026 •

edited

Loading

lolbinarycat left a comment •

edited by rustbot

Loading