Skip to content
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 regression: stable items reexported from unstable modules appear unstable #134702

Closed
tgross35 opened this issue Dec 23, 2024 · 3 comments · Fixed by #134791
Closed

Rustdoc regression: stable items reexported from unstable modules appear unstable #134702

tgross35 opened this issue Dec 23, 2024 · 3 comments · Fixed by #134791
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-bug Category: This is a bug. regression-from-stable-to-stable Performance or correctness regression from one stable version to another. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@tgross35
Copy link
Contributor

tgross35 commented Dec 23, 2024

Previously, stable items that are reexported from unstable modules (to stable modules) showed up as stable, which is correct because the user has a way to access them. However, since 1.83, they show up as unstable. This is accurate in one sense as they can't be stably accessed via the displayed path but is misleading because the types themselves are actually stably usable.

As an example, here is the most recent documentation from the most recent 1.83, as well as nightly https://doc.rust-lang.org/1.83.0/std/ffi/c_str/struct.FromBytesUntilNulError.html:

Image

From 1.82 https://doc.rust-lang.org/1.82.0/std/ffi/c_str/struct.FromBytesUntilNulError.html:

Image

And then 1.69, before it moved modules https://doc.rust-lang.org/1.69.0/core/ffi/struct.FromBytesUntilNulError.html:

Image

There was a related issue in the near past with method signatures https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/Moving.20to.20a.20module.20breaks.20stability.20indicators

@tgross35 tgross35 added A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-bug Category: This is a bug. regression-from-stable-to-stable Performance or correctness regression from one stable version to another. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Dec 23, 2024
@rustbot rustbot added I-prioritize Issue: Indicates that prioritization has been requested for this issue. needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Dec 23, 2024
@tgross35 tgross35 removed I-prioritize Issue: Indicates that prioritization has been requested for this issue. needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Dec 23, 2024
@tgross35
Copy link
Contributor Author

One related thing: even though the type can be accessed stably, copying the path via the button gives a path that is only usable with unstable e.g. std::ffi::c_str::FromBytesUntilNulError. It may be nice to instead provide the fully stable path for anything that falls into this category (i.e. std::ffi::FromBytesUntilNulError).

@GrigorenkoPV
Copy link
Contributor

Image

For example, #134692 moves Mutex and MutexGuard to a new #[unstable] pub mod std::sync::poison.
They are then reexported with a #[stable] #[doc(inline)] pub use in std::sync.

However, a [`Mutex::lock`] link in the doc for MutexGuard gets resolved as std::sync::poison::Mutex::lock and not std::sync::Mutex::lock (same with try_lock in the screenshot above).

@notriddle
Copy link
Contributor

notriddle commented Dec 24, 2024

The main ffi module shows the types as re-exported, instead of inlined.

https://doc.rust-lang.org/1.83.0/std/ffi/index.html#reexports

Re-exports

pub use self::c_str::FromBytesUntilNulError;
pub use self::c_str::FromBytesWithNulError;
pub use self::c_str::FromVecWithNulError;
pub use self::c_str::IntoStringError;
pub use self::c_str::NulError;

To fix that, the use statements need marked with #[doc(inline)]. Fixing this, as in returning to the status quo, seems weird. After all, they aren't accessible at the path given.

@bors bors closed this as completed in c1447e3 Dec 27, 2024
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Dec 27, 2024
Rollup merge of rust-lang#134791 - notriddle:notriddle/inline-ffi-error-types, r=tgross35

docs: inline `std::ffi::c_str` types to `std::ffi`

Rustdoc has no way to show that an item is stable, but only at a different path. `std::ffi::c_str::NulError` is not stable, but `std::ffi::NulError` is.

To avoid marking these types as unstable when someone just wants to follow a link from `CString`, inline them into their stable paths.

Fixes rust-lang#134702

r? `@tgross35`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-bug Category: This is a bug. regression-from-stable-to-stable Performance or correctness regression from one stable version to another. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants