rustdoc `doc_auto_cfg` incorrectly picks up cfg's

[Mark-Simulacrum]

View all comments

NOTE(camelid): This bug is now feature-gated behind the doc_auto_cfg flag and, as such, is no longer a regression. The original issue text follows.

---

For example, https://doc.rust-lang.org/nightly/std/primitive.usize.html#method.trailing_zeros has a tag indicating it is only supported on 64-bit, but in practice the method is defined on 32-bit as well; it's just defined separately from that definition.

This seems like it'll probably hurt particularly new users who may be annoyed at the lack of cross-target compatibility in such a method -- if we can't design a fix, I'd prefer that we disable the autosetting of cfgs for now, since it seems like this is likely to be widespread.

[Mark-Simulacrum]

cc @rust-lang/rustdoc

[jyn514]

@Mark-Simulacrum this doesn't need rustdoc changes, you can just remove feature(doc_cfg) from the standard library (and replace it with the manual cfgs from before). I don't think we should disable it for the rest of the ecosystem just because the standard library has some weird edge cases.

[GuillaumeGomez]

It's not a regression from stable to beta but from nightly to nightly.

@jyn514 It's actually because of rustdoc here:

#[cfg(target_pointer_width = "32")]
#[lang = "usize"]
impl usize {
    widening_impl! { usize, u64, 32 }
    uint_impl! { usize, u32, isize, 32, 4294967295, 8, "0x10000b3", "0xb301", "0x12345678",
    "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
    usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}

#[cfg(target_pointer_width = "64")]
#[lang = "usize"]
impl usize {
    widening_impl! { usize, u128, 64 }
    uint_impl! { usize, u64, isize, 64, 18446744073709551615, 12, "0xaa00000000006e1", "0x6e10aa",
    "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
    "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
    usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}

It picks automatically the #[cfg(target_pointer_width = "...")] since we merged #89596. The solution here would be to use cfg_hide on them.

[jyn514]

@GuillaumeGomez cfg(hide) is global for a crate. I don't think it makes sense to hide it for all 64-bit specific items in libstd.

[GuillaumeGomez]

Ah my bad, I thought we could use it both globally and locally. In such a case, it would make sense actually.

[Nemo157]

You can apply a manual #[doc(cfg())] on these items to override the #[cfg].

[GuillaumeGomez]

How would that help? You can only add cfg, not remove them, no?

[Nemo157]

No, a doc(cfg) on an item replaces the cfg on that item for documentation purposes.

[GuillaumeGomez]

Weird, but I guess it would solve the issue. Are you ok with this solution @Mark-Simulacrum ?

[Mark-Simulacrum]

I don't think we should disable it for the rest of the ecosystem just because the standard library has some weird edge cases.

This is not a "weird edge case", afaict, it will affect any case where there are two separate items defined with cfgs on each (likely non-overlapping so that the items don't introduce errors in the build). That is very common, I expect. I think we should disable it for core/alloc/std at least for now. The alternative of adding doc(cfg) overrides a bunch of places, and maintaining them, seems like a nightmare (you need to think about it for every cfg you add, which is annoying and kinda worse than what we had before this new support landed).

It's not a regression from stable to beta but from nightly to nightly.

The stable documentation for std does not show this bug, but beta does, so I consider it a stable-to-beta regression.

It does seem like doc_cfg is not yet stabilized, so once the std docs are fixed this stops being a regression (just an unfortunate behavior/bug in the feature). Though I presume any external users building with rustdoc nightly (e.g., docs.rs) are also affected and have similar "bugs" in their docs that they didn't yet notice.