[rustdoc] Update `doc_cfg` hide/show syntax by GuillaumeGomez · Pull Request #157871 · rust-lang/rust

GuillaumeGomez · 2026-06-13T18:47:22Z

Part of #43781.

As discussed at the all-hands with the rustdoc team, we decided to follow the check-cfg syntax. So this PR implements it.

Considering @Urgau made the check-cfg implementation, I'll set them as reviewer here.

r? @Urgau

rustbot · 2026-06-13T18:47:25Z

Some changes occurred in compiler/rustc_hir/src/attrs

cc @jdonszelmann, @JonathanBrouwer

Some changes occurred in compiler/rustc_attr_parsing

cc @jdonszelmann, @JonathanBrouwer

GuillaumeGomez · 2026-06-14T08:36:41Z

Fixed CI. :)

Urgau

Looks pretty good. Some changes around none() and we should be in a good place.

View changes since this review

Urgau · 2026-06-16T17:21:12Z

+#[derive(Clone, Debug, StableHash, Encodable, Decodable, PrintAttribute, PartialEq)]
+pub enum DocCfgHideShowValue {
+    Any(Span),
+    List(ThinVec<(Symbol, Span)>),
+}
+
 #[derive(Clone, Debug, StableHash, Encodable, Decodable, PrintAttribute)]
-pub struct CfgInfo {
-    pub name: Symbol,
-    pub name_span: Span,
-    pub value: Option<(Symbol, Span)>,
+pub struct DocCfgHideShow {
+    /// If `Some`, then `cfg` without values (like `cfg(windows)`) will be shown/hidden.
+    /// The `Span` comes from where this value was set.
+    pub only_key: Option<Span>,
+    /// The values of this `cfg` to shown/hidden.
+    pub values: DocCfgHideShowValue,
 }


This representation of the values of #[cfg] diverges from the compiler ExpectedValues for the none value (ie #[cfg(foo)]).

Normally we represent it with an Option<Symbol> where None is the absence of value, but this representation states that a value is only a Symbol and that it cannot be mixed with an "only key", but this ignores that mixed cases like #[cfg(foo)], #[cfg(foo = "12")], #[cfg(foo = "16")], ...

Suggested change

#[derive(Clone, Debug, StableHash, Encodable, Decodable, PrintAttribute, PartialEq)]

pub enum DocCfgHideShowValue {

Any(Span),

List(ThinVec<(Symbol, Span)>),

}

#[derive(Clone, Debug, StableHash, Encodable, Decodable, PrintAttribute)]

pub struct CfgInfo {

pub name: Symbol,

pub name_span: Span,

pub value: Option<(Symbol, Span)>,

pub struct DocCfgHideShow {

/// If `Some`, then `cfg` without values (like `cfg(windows)`) will be shown/hidden.

/// The `Span` comes from where this value was set.

pub only_key: Option<Span>,

/// The values of this `cfg` to shown/hidden.

pub values: DocCfgHideShowValue,

}

#[derive(Clone, Debug, StableHash, Encodable, Decodable, PrintAttribute, PartialEq)]

pub enum DocCfgHideShowValue {

Any(Span),

List(ThinVec<(Option<Symbol>, Span)>),

}

#[derive(Clone, Debug, StableHash, Encodable, Decodable, PrintAttribute)]

pub struct DocCfgHideShow {

/// The values of this `cfg` to shown/hidden.

pub values: DocCfgHideShowValue,

}

But with this approach, you need to have two DocCfgHideShow: one to represent cfg(foo) and another to represent cfg(foo = "bla"). Or did I misunderstand your point?

No, you still only need one DocCfgHideShow and one DocCfgHideShowValue.

The way cfg(foo) would be represented is by having a (None, none_span) inside DocCfgHideShowValue::List.

All the other values, like cfg(foo = "bla") would be (Some("bla"), bla_span)) inside DocCfgHideShowValue::List.

So at the end if you had hide(foo, values(none(), "bla")) it would be represented as:

// imaging this is dbg!() DocCfgHideShow { values: DocCfgHideShowValue::List(vec![ (None, none_span), (Some("bla"), bla_span)), ]) }

But you cannot have an any() and a none() in the same struct then.

any() already implies none(), there is no need for both of them to be specified at the same time.

Also for --check-cfg specifying both is rejected.

So you cannot say "all values but only if there is a value"?

So you cannot say "all values but only if there is a value"?

No, not currently. The same is also not possible with a literal like "bar". There hasn't been a desire to introduce a "all values expect ...".

For the record, we talked about this extensively in DM and ended-up with two possible way forward:

allow conflicting hide(...) and show(...) on the same level: auto_cfg(hide(windows, values(any())), show(windows))

change the effect of show(...) to not take into account hide(...), but instead show everything inside (...) and hide everything else

instead of only effecting what was hidden by a previous hide(...)

Both solution would I think work, and I don't have a preference, so feel free to do either of them.

The end goal is to be consistent with --check-cfg: any() implies none().

I'll go with 1. as I find it more elegant and coherent with how cfg works.

rustbot · 2026-06-17T15:08:52Z

These commits modify tests/rustdoc-json.
rustdoc-json is a public (but unstable) interface.

Please ensure that if you've changed the output:

It's intentional.
The FORMAT_VERSION in src/librustdoc-json-types is bumped if necessary.

cc @aDotInTheVoid, @obi1kenobi

GuillaumeGomez · 2026-06-17T15:09:24Z

Correctly handled values(), added test for values("a", none()), add a rustdoc-json test and updated the book.

GuillaumeGomez · 2026-06-17T15:15:43Z

Well, fmt makes me sad on this one but it's fine. :')

GuillaumeGomez · 2026-06-24T16:33:17Z

Implemented the correct handling of values(any()) and remove the show/hide conflict, allowing cases that were not possible otherwise.

GuillaumeGomez · 2026-06-24T16:39:19Z

And because I had to forget something, I updated the docs too. :)

…tdoc book

…any())`

rustbot · 2026-06-26T10:49:26Z

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.

GuillaumeGomez · 2026-06-26T10:49:44Z

Fixed merge conflict.

Urgau

Thanks for working on it. LGTM

View changes since this review

Urgau · 2026-06-27T13:02:21Z

@bors r+

rust-bors · 2026-06-27T13:02:24Z

📌 Commit 702445c has been approved by Urgau

It is now in the queue for this repository.

🌲 The tree is currently closed for pull requests below priority 1. This pull request will be tested once the tree is reopened.

…uwer Rollup of 13 pull requests Successful merges: - #157871 ([rustdoc] Update `doc_cfg` hide/show syntax) - #158234 (Cross-referencing tuple_trait tracking issue, source and the Unstable Book) - #158480 (add smoketest for std::net::hostname) - #157625 (Use infer tys for synthetic params when lowering const paths point to fns) - #158290 (add crashtests [1/N]) - #158306 (tests: modify s390x vector test to be robust to instruction scheduling) - #158313 (Move `check_target_feature` into the attribute parser) - #158431 (More lint cleanups) - #158452 (Add missing links in integer docs) - #158467 (Add proc macro for unused assignments and corresponding test) - #158472 (Add regression test for unexpected pointer dereference issue) - #158475 (Fix doc comment on get_debug_as_hex.) - #158476 (Fix doc comment on FormattingOptions::new().)

JonathanBrouwer · 2026-06-27T20:24:20Z

@rust-timer build 0a46792
Perf run for #158487

rust-timer · 2026-06-27T21:04:31Z

Finished benchmarking commit (0a46792): comparison URL.

Overall result: ❌ regressions - please read:

Benchmarking means the PR may be perf-sensitive. It's automatically marked not fit for rolling up. Overriding is possible but disadvised: it risks changing compiler perf.

Next, please: If you can, justify the regressions found in this try perf run in writing along with @rustbot label: +perf-regression-triaged. If not, fix the regressions and do another perf run. Neutral or positive results will clear the label automatically.

@bors rollup=never
@rustbot label: -S-waiting-on-perf +perf-regression

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	0.3%	[0.2%, 0.5%]	7
Regressions ❌ (secondary)	0.4%	[0.2%, 0.6%]	18
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	0.3%	[0.2%, 0.5%]	7

Max RSS (memory usage)

Results (primary 5.7%, secondary 2.8%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	5.7%	[5.6%, 5.8%]	2
Regressions ❌ (secondary)	5.3%	[1.0%, 9.5%]	5
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-3.5%	[-5.2%, -1.8%]	2
All ❌✅ (primary)	5.7%	[5.6%, 5.8%]	2

Cycles

Results (primary 2.9%, secondary 1.5%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	2.9%	[2.9%, 2.9%]	1
Regressions ❌ (secondary)	4.4%	[3.1%, 5.2%]	6
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-2.8%	[-3.4%, -2.1%]	4
All ❌✅ (primary)	2.9%	[2.9%, 2.9%]	1

Binary size

This perf run didn't have relevant results for this metric.

Bootstrap: 485.171s -> 485.604s (0.09%)
Artifact size: 393.14 MiB -> 393.21 MiB (0.02%)

rustbot assigned Urgau Jun 13, 2026

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the doc_cfg-syntax branch from 0406a13 to 2c62c7f Compare June 13, 2026 20:47

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the doc_cfg-syntax branch from 2c62c7f to 7eaade0 Compare June 14, 2026 00:42

Urgau reviewed Jun 16, 2026

View reviewed changes

Urgau added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 16, 2026

GuillaumeGomez force-pushed the doc_cfg-syntax branch from 7eaade0 to fba8015 Compare June 17, 2026 15:08

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the doc_cfg-syntax branch from fba8015 to d38a2c9 Compare June 17, 2026 15:15

GuillaumeGomez force-pushed the doc_cfg-syntax branch from 230486d to 7a047c7 Compare June 24, 2026 16:38

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the doc_cfg-syntax branch from 7a047c7 to 771318c Compare June 25, 2026 12:33

This comment has been minimized.

Sign in to view

GuillaumeGomez added 8 commits June 26, 2026 12:26

Update doc_cfg hide/show syntax

810d2db

Update alloc and core to new doc_cfg syntax

dc7a2ce

Update rustdoc to use new doc_cfg syntax

f22107c

Move doc-cfg tests into the right location

3c92a3c

Add more regression tests for doc(auto_cfg())

c383e5c

Update syntax information for doc(auto_cfg(hide/show())) in the rus…

a3ad068

…tdoc book

Add rustdoc-json test for doc_cfg

9653fd0

Remove doc_cfg show/hide conflict error and correctly handle `values(…

702445c

…any())`

GuillaumeGomez force-pushed the doc_cfg-syntax branch from 771318c to 702445c Compare June 26, 2026 10:49

Urgau approved these changes Jun 27, 2026

View reviewed changes

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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jun 27, 2026

JonathanBrouwer mentioned this pull request Jun 27, 2026

Rollup of 13 pull requests #158487

Merged

rust-bors Bot merged commit eb804b3 into rust-lang:main Jun 27, 2026
13 checks passed

rustbot added this to the 1.98.0 milestone Jun 27, 2026

This comment has been minimized.

Sign in to view

rustbot added the perf-regression Performance regression. label Jun 27, 2026

GuillaumeGomez deleted the doc_cfg-syntax branch June 27, 2026 22:31

Uh oh!

Uh oh!

Conversation

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

Uh oh!

Uh oh!

rustbot commented Jun 13, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Jun 14, 2026

Uh oh!

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

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustbot commented Jun 17, 2026

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 17, 2026

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 17, 2026

Uh oh!

GuillaumeGomez commented Jun 24, 2026

Uh oh!

GuillaumeGomez commented Jun 24, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

rustbot commented Jun 26, 2026

Uh oh!

GuillaumeGomez commented Jun 26, 2026

Uh oh!

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

Urgau commented Jun 27, 2026

Uh oh!

rust-bors Bot commented Jun 27, 2026

Uh oh!

Uh oh!

JonathanBrouwer commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

rust-timer commented Jun 27, 2026

Overall result: ❌ regressions - please read:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

GuillaumeGomez commented Jun 13, 2026 •

edited by rustbot

Loading

Urgau left a comment •

edited by rustbot

Loading

Urgau left a comment •

edited by rustbot

Loading

JonathanBrouwer commented Jun 27, 2026 •

edited

Loading