fix(doc): remove incorrect “available on 64-bit only” portability note on [iu]size

[ShE3py]

Fixes #149786; the portability note is now shown on stable docs:
https://doc.rust-lang.org/1.93.0/std/primitive.usize.html#impl-usize

Tried to look for others cases, surprisingly others aren't marked as only available on 64-bit:
https://doc.rust-lang.org/1.93.0/std/primitive.u8.html#impl-TryFrom<usize>-for-u8

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

Lines 428 to 432 in 254b596

	#[cfg(target_pointer_width = "64")]
	mod ptr_try_from_impls {
	use super::TryFromIntError;
	impl_try_from_upper_bounded!(usize => u8, u16, u32);

And looking for cfg directly followed by an impl (regex: #\[cfg\(target_pointer_width = "\d{2}"\)\]\s*impl ) only matches i/usize.

@rustbot label +A-docs

[rustbot]

r? @tgross35

rustbot has assigned @tgross35.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[tgross35]

This LGTM as a potential workaround, but I'd like to hear back from @rust-lang/rustdoc as to whether they might want to fix it on their side. Asked about expected behavior at #149786 (comment).

If we wind up going this route or if the rustdoc fixes would take a while, this can be beta nominated.

[GuillaumeGomez]

Wouldn't it be simpler to disable the whole feature for the whole file instead?

#![doc(auto_cfg = false)]

[ShE3py]

That would be equivalent, but this will also disable auto_cfg on all core::num's submodules and could hide cfgs in future implementations, not sure which one is preferable.

[GuillaumeGomez]

Multiple solutions:

• Re-enable the feature with #[doc(auto_cfg = true)] on the submodules.
• Use #[doc(cfg())] on the items you don't want any annotations to.
• Keep the current settings with #[doc(auto_cfg(hide(target_pointer_width = ...)))]

[notriddle]

I can't think of any way that this could be "fixed" in rustdoc. To infer that the primitive is actually available on all pointer widths, it would need to see the AST with all of the cfg-ed out parts still present, which probably won't happen any time soon.

[tgross35]

@rustbot author for adjusting to one of the above solutions. @bjoernager's idea at #149786 (comment) would probably be the most accurate.

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[ShE3py]

Not sure about splitting the int_impl! macros since “portable” functions would depend on the conditionals functions and thus be transitively non-portable.

As the cfg-gating is mostly only used in doc-comments, alternative solution:

macro_rules! uint_impl {
    (
        Self = $SelfT:ty,
        SignedT = $SignedT:ident,
        
        $(#[cfg($Pred:meta)] {
            ActualT = $ActualT:ident,
            MAX = $MaxV:literal,
        })+
    ) => {
        // [...]
        /// # Examples
        ///
        /// ```
        $(#[cfg_attr($Pred, doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($MaxV), ");"))])+
        /// ```
        #[stable(feature = "assoc_int_consts", since = "1.43.0")]
        pub const MAX: Self = !0;
    }
}

uint_impl! {
    Self = usize,
    SignedT = isize,
    
    #[cfg(target_pointer_width = "64")] {
        ActualT = u64,
        MAX = 18446744073709551615,
    }
    
    #[cfg(target_pointer_width = "32")] {
        ActualT = u32,
        MAX = 4294967295,
    }
}

And using #[cfg(true)] for other integers.

---

This fix should preserve the labels for the target-specific constant values, which are actually quite appropriate.

Constant values (e.g. MAX) are not shown in the definition, but in the example tests, we could add a comment e.g.

pub const MAX: usize

The largest value that can be represented by this integer type (2⁶⁴ − 1 on 64-bit targets).

Examples

assert_eq!(usize::MAX, 18446744073709551615); // on 64-bit targets

[bjoernager]

Not sure about splitting the int_impl! macros since “portable” functions would depend on the conditionals functions and thus be transitively non-portable.

"Portable" here applies to the item body/value, not the item itself. All interfaces are provided on all targets; methods have the exact same prototypes, and constants have the exact same identifiers but some with conditional values.

[ShE3py]

For instance, MAX is defined as !0, BITS as MAX.count_ones(), so their bodies are portable. The MAX passed to the uint_impl! is used for doc-testing (assert_eq!(usize::MAX, 65535)), and I can't really generate portable bodies in one macro and their non-portable doc-strings in another.

The only non-portable bodies are the ones that actually casts to the underlying integer, e.g. self as $ActualT.