rustdoc: Tracking issue for `#[doc(cfg)]` and automatically documented `#[cfg]`s

[kennytm]

View all comments

This is a tracking issue for RFC 3631.
The feature gate for this doc_cfg (doc_cfg_hide and doc_auto_cfg were removed in favor this overarching one).

Part of #1998.

Note

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.

A tracking issue is however not meant for large scale discussion, questions, or bug reports.
Instead, open a dedicated issue for the specific matter or post in the #t-rustdoc Zulip channel.

Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.

Steps

• Experimental implementation
• Adjust documentation
• Write an RFC
• Update implementation to match RFC
• Check performance impact on big crates
• Stabilization PR (see instructions on forge): Stabilize doc_cfg feature #150055

Open issues

• Long lists of doc_cfg targets are not sorted in a useful way #156391

Unresolved questions

Resolved questions

• Should we change the syntax of hiding/showing cfgs? The current syntax, #[doc(cfg(hide(…)))] & #[doc(cfg(show(…)))] might not be super forward compatible given recent T-lang discussions about potential "general cfg predicates" like a potential #[cfg(rust_version(…))] or #[cfg(since(…))] (notice the (…) instead of the = …!)) (cc Decision: Use the condition name rust_version for RFC 2523 #142651, #t-lang > cfg(version(..)) as a version comparison predicate) meaning hide(…) & show(…) could become ambiguous in the feature (doc cfg hide/show vs. custom predicate called hide/show)
  • Done in Implement RFC 3631: add rustdoc doc_cfg features #138907
• We're lacking a way to hide cfgs where "the key is fixed but the value is not not". Rephrased there's no way to say "hide FIXED_KEY="ANY_VALUE" for all strings ANY_VALUE given a fixed FIXED_KEY" since hide(FIXED_KEY) would only hide FIXED_KEYs without a value (!) (as --cfg FIXED_KEY and --cfg FIXED_KEY='"FIXED_VALUE"' are basically entirely separate cfgs)
  • Done in Implement RFC 3631: add rustdoc doc_cfg features #138907

Implementation history

• Expose all OS-specific modules in libstd doc. #43348
• Unify rustc and rustdoc parsing of cfg() #84442
• Make cfg imply doc(cfg) #89596
• Split doc_cfg and doc_auto_cfg features #90502
• Update documentation for doc_cfg feature #92818
• Implement RFC 3631: add rustdoc doc_cfg features #138907