[rustdoc] Update doc_cfg hide/show syntax

[GuillaumeGomez]

View all comments

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]

Some changes occurred in compiler/rustc_hir/src/attrs

cc @jdonszelmann, @JonathanBrouwer

Some changes occurred in compiler/rustc_attr_parsing

cc @jdonszelmann, @JonathanBrouwer

[GuillaumeGomez]

Fixed CI. :)

[Urgau]

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

View changes since this review

[Urgau]

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,
	}

[GuillaumeGomez]

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?

[Urgau]

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)),
    ])
}

[GuillaumeGomez]

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

[Urgau]

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.

[GuillaumeGomez]

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

[Urgau]

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:

1. allow conflicting hide(...) and show(...) on the same level: auto_cfg(hide(windows, values(any())), show(windows))
2. 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().

[GuillaumeGomez]

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

[rustbot]

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]

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

[GuillaumeGomez]

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

[GuillaumeGomez]

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

[GuillaumeGomez]

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

[rustbot]

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]

Fixed merge conflict.