`rustdoc` reports wrong config conditions for `impl LowerExp for integers`

[Urhengulas]

View all comments

Actual Output

In the generated documentation for the core library, it reports LowerExp to be only implemented for integers on WebAssembly. See: https://doc.rust-lang.org/1.94.0/core/fmt/trait.LowerExp.html#impl-LowerExp-for-i8.

This probably affects other trait implementations as well.

Expected Outcome

LowerExp is available for all integer types on all platforms, therefore I expect it to report nothing regarding configs.

Version

1.94.0

Additional Details

In my understanding the problem is a combination of:

1. First, how the implementation is generated:

   rust/library/core/src/fmt/num.rs

   Lines 594 to 612 in 3bc6ea5

   	// Include wasm32 in here since it doesn't reflect the native pointer size, and
   	// often cares strongly about getting a smaller code size.
   	#[cfg(any(target_pointer_width = "64", target_arch = "wasm32"))]
   	mod imp {
   	use super::*;
   	impl_Display!(i8, u8, i16, u16, i32, u32, i64, u64, isize, usize; as u64 into display_u64);
   	impl_Exp!(i8, u8, i16, u16, i32, u32, i64, u64, isize, usize; as u64 into exp_u64);
   	}
   	#[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))]
   	mod imp {
   	use super::*;
   	impl_Display!(i8, u8, i16, u16, i32, u32, isize, usize; as u32 into display_u32);
   	impl_Display!(i64, u64; as u64 into display_u64);
   	impl_Exp!(i8, u8, i16, u16, i32, u32, isize, usize; as u32 into exp_u32);
   	impl_Exp!(i64, u64; as u64 into exp_u64);
   	}
   	impl_Exp!(i128, u128; as u128 into exp_u128);

   In the end the trait is implemented for all pointer sizes, but it is different depending on the pointer size.

2. And second that the pointer size configs are hidden:

   rust/library/core/src/lib.rs

   Lines 54 to 74 in 3bc6ea5

   	#![doc(auto_cfg(hide(
   	no_fp_fmt_parse,
   	target_pointer_width = "16",
   	target_pointer_width = "32",
   	target_pointer_width = "64",
   	target_has_atomic = "8",
   	target_has_atomic = "16",
   	target_has_atomic = "32",
   	target_has_atomic = "64",
   	target_has_atomic = "ptr",
   	target_has_atomic_equal_alignment = "8",
   	target_has_atomic_equal_alignment = "16",
   	target_has_atomic_equal_alignment = "32",
   	target_has_atomic_equal_alignment = "64",
   	target_has_atomic_equal_alignment = "ptr",
   	target_has_atomic_load_store = "8",
   	target_has_atomic_load_store = "16",
   	target_has_atomic_load_store = "32",
   	target_has_atomic_load_store = "64",
   	target_has_atomic_load_store = "ptr",
   	)))]

If I remove the target_pointer_widths from the doc(auto_cfg(hide(..., then it gets shown like this (which is not really better tbh):

[jyn514]

@rustbot label A-docs F-doc_auto_cfg

[eggyal]

Is this really an issue for T-rustdoc and F-doc_auto_cfg - aren't they all behaving as they should? I rather think this is just a libs issue, where the use of doc(auto_cfg) needs tweaking/overriding in this case.

@rustbot label -F-doc_auto_cfg -T-rustdoc +T-libs -needs-triage

[jyn514]

@eggyal what would the correct usage be? is there a way to override the auto_cfg behavior for individual items?

[eggyal]

https://doc.rust-lang.org/rustdoc/unstable-features.html#doccfg-and-docauto_cfg

All of these attributes can be added to a module or to the crate root, and they will be inherited by the child items unless another attribute overrides it. This is why “opposite” attributes like auto_cfg(hide(...)) and auto_cfg(show(...)) are provided: they allow a child item to override its parent.

Also https://doc.rust-lang.org/rustdoc/unstable-features.html#doccfg

If doc(auto_cfg) is enabled on the item, doc(cfg) will override it

Also perhaps most relevant https://doc.rust-lang.org/rustdoc/unstable-features.html#docauto_cfgdocauto_cfg--truedocauto_cfg--false

In some situations, the detailed conditional compilation rules used to implement the feature might not serve as good documentation (for example, the list of supported platforms might be very long, and it might be better to document them in one place). To turn it off, add the #[doc(auto_cfg = false)] attribute on the item.

[eggyal]

Alternatively the code could be restructured so that there is in fact just a single impl across all configurations, and only the methods within those implementations differ by conditional compilation. I'm not sure whether libs have a preference for how this is done, or indeed if the issue has even arisen before.

[Urhengulas]

@eggyal I am just trying to overwrite the auto_cfg configuration for this module only but it does not seem to work as I would expect.

auto_cfg(show/hide(...))

Using #[doc(auto_cfg(show/hide(...)))] does not seem to have any effect. I don't think this is intended but maybe I am misunderstanding how it should work.

#![doc(auto_cfg(hide(target_arch = "wasm32")))]

Adding #![doc(auto_cfg(hide(target_arch = "wasm32")))] to either the module or the macro invocation does not change anything, the generated rustdoc stays the same.

diff

diff --git a/library/core/src/fmt/num.rs b/library/core/src/fmt/num.rs
index b1df3ff9f69..81e7057e045 100644
--- a/library/core/src/fmt/num.rs
+++ b/library/core/src/fmt/num.rs
@@ -1,5 +1,7 @@
 //! Integer and floating-point number formatting
 
+#![doc(auto_cfg(hide(target_arch = "wasm32")))]
+
 use crate::fmt::NumBuffer;
 use crate::mem::MaybeUninit;
 use crate::num::fmt as numfmt;
@@ -594,6 +596,7 @@ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 
 // Include wasm32 in here since it doesn't reflect the native pointer size, and
 // often cares strongly about getting a smaller code size.
+#[doc(auto_cfg(hide(target_arch = "wasm32")))]
 #[cfg(any(target_pointer_width = "64", target_arch = "wasm32"))]
 mod imp {
     use super::*;
@@ -601,6 +604,7 @@ mod imp {
     impl_Exp!(i8, u8, i16, u16, i32, u32, i64, u64, isize, usize; as u64 into exp_u64);
 }
 
+#[doc(auto_cfg(hide(target_arch = "wasm32")))]
 #[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))]
 mod imp {
     use super::*;

#![doc(auto_cfg(show(target_pointer_width = "64")))]

Adding #![doc(auto_cfg(show(target_pointer_width = "64")))] also has no effect.

diff

diff --git a/library/core/src/fmt/num.rs b/library/core/src/fmt/num.rs
index b1df3ff9f69..d54a824be30 100644
--- a/library/core/src/fmt/num.rs
+++ b/library/core/src/fmt/num.rs
@@ -1,5 +1,7 @@
 //! Integer and floating-point number formatting
 
+#![doc(auto_cfg(show(target_pointer_width = "64")))]
+
 use crate::fmt::NumBuffer;
 use crate::mem::MaybeUninit;
 use crate::num::fmt as numfmt;
@@ -594,6 +596,7 @@ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 
 // Include wasm32 in here since it doesn't reflect the native pointer size, and
 // often cares strongly about getting a smaller code size.
+#[doc(auto_cfg(show(target_pointer_width = "64")))]
 #[cfg(any(target_pointer_width = "64", target_arch = "wasm32"))]
 mod imp {
     use super::*;
@@ -601,6 +604,7 @@ mod imp {
     impl_Exp!(i8, u8, i16, u16, i32, u32, i64, u64, isize, usize; as u64 into exp_u64);
 }
 
+#[doc(auto_cfg(show(target_pointer_width = "64")))]
 #[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))]
 mod imp {
     use super::*;

doc(cfg(all()))

The only option I found that generates the rustdoc without any "only available on ..." note is #[doc(cfg(all()))] on the macro invocation. Which is an okay workaround but does not seem like a proper solution.

diff

diff --git a/library/core/src/fmt/num.rs b/library/core/src/fmt/num.rs
index b1df3ff9f69..fb426bebe3a 100644
--- a/library/core/src/fmt/num.rs
+++ b/library/core/src/fmt/num.rs
@@ -594,6 +594,7 @@ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 
 // Include wasm32 in here since it doesn't reflect the native pointer size, and
 // often cares strongly about getting a smaller code size.
+#[doc(cfg(all()))]
 #[cfg(any(target_pointer_width = "64", target_arch = "wasm32"))]
 mod imp {
     use super::*;
@@ -601,6 +602,7 @@ mod imp {
     impl_Exp!(i8, u8, i16, u16, i32, u32, i64, u64, isize, usize; as u64 into exp_u64);
 }
 
+#[doc(cfg(all()))]
 #[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))]
 mod imp {
     use super::*;