rust-lang / rust

Empowering everyone to build reliable and efficient software.
https://www.rust-lang.org
Other
96.79k stars 12.5k forks source link

Rustdoc doesn't list all cfg's required for an item to be included #128563

Open xd009642 opened 1 month ago

xd009642 commented 1 month ago

In the tokio RuntimeMetrics docs the majority of metrics require --cfg=tokio_unstable. Howver, some also require a target architecture with 64 bit atomics. For metrics which require both of these features rustdoc only shows one of them. Linked is an example: https://docs.rs/tokio/latest/tokio/runtime/struct.RuntimeMetrics.html#method.spawned_tasks_count

Here it says "Available on target_has_atomic="64" only." But it should say something like "Only available with target_has_atomic="64" and tokio_unstable."

bjorn3 commented 1 month ago

You have a cfg_64bit_metrics! nested in a cfg_unstable_metrics!. It seems that the cfg_unstable_metrics! applies the #[doc(cfg)] to the cfg_64bit_metrics! macro invocation itself, which has no effect, rather than applying it to every item in the cfg_64bit_metrics! expansion.

xd009642 commented 1 month ago

Makes sense, is making this pattern work and show the correct cfg's desirable or too much faff and users should just change the way they cfg out items? I'm fine with closing this personally as it's clear how to resolve it as a user