Implement RFC 3631: add rustdoc doc_cfg features #138907

GuillaumeGomez · 2025-03-24T22:50:33Z

This implementation actually resulted in a lot of simplifications:

All cfg computation is now done in one place: propagate_doc_cfg.rs. Because (trait) impls are not retrieved at the same time as the other items, we cannot perform this computation in the clean process, it needs to be after.
Because there is cfg inheritance, we can keep track of them in one place (in propagate_doc_cfg.rs), meaning we don't need to copy an item's attributes to its children anymore. Only exception: impl items. For them we clone only cfg attributes.
propagate_doc_cfg.rs is also now much simpler, much less need to keep track of parents, since everything we need is handled by the new CfgInfo type.
I also suspect that Cfg::simplify_with could either be removed or at least used directly into propagate_doc_cfg.rs when we compute cfgs. Considering how big the PR already is, I'll do it in a follow-up.

I didn't remove the doc_cfg* features in this PR because some dependencies used in rustc (like stdarch) are using it, so we need to have a nightly released with this PR before I can switch to the new feature.

r? ghost

petrochenkov · 2025-03-25T09:48:06Z

What remains to be done:

I'd also want to block the stabilization on landing #138844 to avoid a stable rustdoc feature relying on externally observable hacks in rustc.
The crater run in #138844 returned mostly clean, so I expect it to land soon.

GuillaumeGomez · 2025-03-25T10:36:45Z

Noted! And that will be a nice improvement, thanks!

Just one thing left for the cfg expansion missing: #[cfg_attr(blabla, derive(Debug))]. In this case, the cfg is not kept in the generated derive items. It's been in my TODO list for a long time now. ^^'

petrochenkov · 2025-03-25T10:49:31Z

Just one thing left for the cfg expansion missing: #[cfg_attr(blabla, derive(Debug))]

Do you mean like in #138515? :)

GuillaumeGomez · 2025-03-25T10:52:03Z

You're my hero! Gonna need to handle this new attribute then. :)

bors · 2025-03-25T17:53:10Z

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

bors · 2025-03-27T19:41:02Z

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

bors · 2025-08-24T23:26:02Z

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

…chapter

…ure(doc_cfg)]`

GuillaumeGomez · 2025-08-25T13:26:50Z

Fixed merge conflict.

rustbot · 2025-08-25T13:26:54Z

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.

rustbot · 2025-08-25T13:26:55Z

⚠️ 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.
- 20b7555

lolbinarycat · 2025-08-25T15:29:07Z

src/doc/rustdoc/src/unstable-features.md

+
+If no argument is specified (ie `#[doc(auto_cfg)]`), it's the same as writing `#[doc(auto_cfg = true)]`.
+
+### `#[doc(cfg(...))]`


It seems a bit odd to have doc(cfg(...)) listed in between two different forms of doc(auto_cfg)

lolbinarycat · 2025-08-25T15:32:25Z

src/doc/rustdoc/src/unstable-features.md

+```text
+Available on (Windows or Unix) and non-Unix only.
+```


This case seems like something that could be improved in the future, but mostly unrelated to the feature being added here

lolbinarycat · 2025-08-25T15:37:37Z

src/librustdoc/clean/inline.rs

+    // doesn't matter at this point.
+    //
+    // We need to pass this empty `CfgInfo` because `merge_attrs` is used when computing the `cfg`.
+    let (merged_attrs, cfg) = merge_attrs(cx, load_attrs(cx, did), attrs, &mut CfgInfo::default());


seems slightly inefficient but probably acceptable...

lolbinarycat · 2025-08-25T15:40:46Z

src/librustdoc/clean/cfg.rs

+                if !hidden.contains(self) {
+                    Some(self.clone())
+                } else {
+                    None
+                }


This means that doc(auto_cfg(hide(feature))) will not hide all features... is this the behavior we want?

This is the one described in the RFC. We cannot hide just all feature = "" cfgs.

lolbinarycat · 2025-08-25T15:43:27Z

src/librustdoc/clean/types.rs

+/// This type keeps track of (doc) cfg information as we go down the item tree.
+#[derive(Clone, Debug)]
+pub(crate) struct CfgInfo {
+    /// List of `doc(auto_cfg(hide(...)))` cfgs.


Suggested change

/// List of `doc(auto_cfg(hide(...)))` cfgs.

/// List of currently active `doc(auto_cfg(hide(...)))` cfgs, minus currently active `doc(auto_cfg(show(...)))` cfgs.

is this correct?

It is indeed!

lolbinarycat · 2025-08-25T15:55:13Z

src/librustdoc/clean/types.rs

+            Some(Arc::new(cfg_info.current_cfg.clone()))
+        }
+    } else {
+        // Since we always want to collect all `cfg` items, we remove the hidden ones afterward.


Saying "always" in a branch that is conditionally executed seems a bit confusing imo.

True, rewording it.

lolbinarycat · 2025-08-25T15:58:52Z

src/librustdoc/passes/propagate_doc_cfg.rs

+        if let Attribute::Unparsed(ref mut normal) = attr
+            && let [ident] = &*normal.path.segments
+        {


I thought we were treating target_feature as doc(cfg(target_feature))? Why do we keep it before and not now?

No, the two are different. We handle attributes copy and doc(cfg()) inheritance in different locations as they rely on different rules. doc(cfg()) inherits from the parent item whereas attributes are copied only for reexports.

lolbinarycat · 2025-08-25T16:05:41Z

tests/rustdoc-ui/doc-cfg.rs

+#[doc(auto_cfg(hide(true)))] //~ ERROR
+#[doc(auto_cfg(hide(42)))] //~ ERROR
+#[doc(auto_cfg(hide("a")))] //~ ERROR
+#[doc(auto_cfg(hide(foo::bar)))] //~ ERROR


Suggested change

#[doc(auto_cfg(hide(true)))] //~ ERROR

#[doc(auto_cfg(hide(42)))] //~ ERROR

#[doc(auto_cfg(hide("a")))] //~ ERROR

#[doc(auto_cfg(hide(foo::bar)))] //~ ERROR

#[doc(auto_cfg(hide(true)))] //~ ERROR

#[doc(auto_cfg(hide(42)))] //~ ERROR

#[doc(auto_cfg(hide("a")))] //~ ERROR

#[doc(auto_cfg(hide(foo::bar)))] //~ ERROR

#[doc(auto_cfg = hide(true)] //~ ERROR

#[doc(auto_cfg = 42)] //~ ERROR

#[doc(auto_cfg = "a")] //~ ERROR

#[doc(auto_cfg = foo::bar)] //~ ERROR

more testcases

lolbinarycat · 2025-08-25T16:12:26Z

tests/rustdoc/doc_auto_cfg_reexports.rs

@@ -0,0 +1,22 @@
+// Checks that `cfg` are correctly applied on inlined reexports.


Shouldn't this also check that cfgs don't get applied on non-inlined reexports?

lolbinarycat · 2025-08-25T16:13:46Z

tests/rustdoc/target-feature.rs

+#![feature(doc_cfg)]
+


Does this mean target_feature will no longer result in any note on stable rustdoc? Or will we still display the attribute itself?

Nothing will be displayed. That's what happens when a PR changing a lot of things waits for too long. ^^'

fmease · 2025-08-26T14:00:53Z

I didn't remove the doc_cfg* features in this PR because some dependencies used in rustc (like stdarch) are using it, so we need to have a nightly released with this PR before I can switch to the new feature.

That's good in any case 👍 This PR should just update the implementation according to the latest version of the merged RFC.

I don't know if we have written that down in our new Forge docs (I hope so) but a feature stabilization would of course require another FCP, the one from the RFC isn't sufficient for that. Moreover, not stabilizing here / now / immediately allows us to gather more user feedback (esp. since the changes made by this PR are non-trivial). Heck, we could even issue a "call for testing" on the official blog – anything to make the eventual stabilization run as smoothly as possible.

GuillaumeGomez · 2025-08-26T14:05:15Z

I don't know if we have written that down in our new Forge docs (I hope so) but a feature stabilization would of course require another FCP, the one from the RFC isn't sufficient for that. Moreover, not stabilizing here / now / immediately allows us to gather more user feedback (esp. since the changes made by this PR are non-trivial). Heck, we could even issue a "call for testing" on the official blog – anything to make the eventual stabilization run as smoothly as possible.

I was planning to keep it unstable for at least a few months and to enable it in some big crates to gather some usage and see if everything is working as expected.

And in any case: any stabilization PR must go through FCP (we should check if we mention that in the forge ^^').

GuillaumeGomez · 2025-08-26T14:05:27Z

Oh also: applied suggestions from @lolbinarycat. :)