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
• Documentation of a re-export doesn't appear on level-two re-export #81893

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
• Remove potential cfgs duplicates #66959
• Simplify doc-cfg rendering based on the current context #77672
• Add tests and improve rendering of cfgs on traits #78678
• 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
• Exclude "test" from doc_auto_cfg #92856
• Fix doc cfg on reexports #101006
• rustdoc: Fix handling of doc_auto_cfg feature for cfg attributes on glob reexport #120548
• Implement RFC 3631: add rustdoc doc_cfg features #138907
• RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features rfcs#3631
• Fix doc_cfg not working as expected on trait impls #153964
• Fix doc_cfg feature for extern items #155967
• [rustdoc] Fix doc_cfg feature on reexports #156073
• [rustdoc] Update doc_cfg hide/show syntax #157871
• [rustdoc] Do not take doc(cfg()) into account when filtering doctests #159014
• [rustdoc] Retrieve cfg_attr information for derived impls for doc_cfg feature #159722
• rustdoc: Small doc_cfg messages improvements #161105