-
Notifications
You must be signed in to change notification settings - Fork 12.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
rustdoc doc_auto_cfg
incorrectly picks up cfg's
#90497
Comments
cc @rust-lang/rustdoc |
@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. |
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 |
@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. |
Ah my bad, I thought we could use it both globally and locally. In such a case, it would make sense actually. |
You can apply a manual |
How would that help? You can only add cfg, not remove them, no? |
No, a |
Weird, but I guess it would solve the issue. Are you ok with this solution @Mark-Simulacrum ? |
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).
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. |
Only if they explicitly opt in with |
That said, I think it would be fine to make the feature gate for "propagate doc_cfg automatically" different than the one for "allow writing |
Ah indeed, I forgot we had a release in between... We also used
Indeed. |
Yes, I don't think there's cause to disable the feature completely for all users -- I had (incorrectly) assumed that the effects would be visible for all users, regardless of the feature gate, but that is not the case. I think splitting out this particular sub-part of the feature would be a good idea (and then we can avoid enabling it in-tree for now). |
Going to send a PR then. |
I did have this bug, and I noticed it (see PyO3/pyo3#1928). For cases like this, where the item is always available but the implementation is different, I fixed this by having cfgs inside of the implementation, rather than on the outside. i.e., instead of using #[cfg(target_pointer_width = "32")]
fn foo(){
// 32 bit impl
}
#[cfg(target_pointer_width = "64")]
fn foo(){
// 64 bit impl
}
I would use fn foo(){
#[cfg(target_pointer_width = "32")]
{
// 32 bit impl
}
#[cfg(target_pointer_width = "64")]
{
// 64 bit impl
}
} That said, I'm not sure how easy that is for the int macros, they are pretty big. |
Would be better for rustdoc to be able to find out on its own but aggregating items with the same name. Just seems really tricky to do... |
@GuillaumeGomez that's the same as solving #1998, I don't think we should make any plans that require solving that. |
At least not before we have a lot of free time on ours hands and solved all other rustdoc issues. :) |
…e, r=jyn514 Split doc_cfg and doc_auto_cfg features Part of rust-lang#90497. With this feature, `doc_cfg` won't pick up items automatically anymore. cc `@Mark-Simulacrum` r? `@jyn514`
doc_auto_cfg
incorrectly picks up cfg's
Updated issue to reflect that this is no longer a regression. |
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.
The text was updated successfully, but these errors were encountered: