Rollup merge of #130798 - lukas-code:doc-stab, r=notriddle

rustdoc: inherit parent's stability where applicable

It is currently not possible for a re-export to have a different stability (https://github.com/rust-lang/rust/issues/30827). Therefore the standard library uses a hack when moving items like `std::error::Error` or `std::net::IpAddr` into `core` by marking the containing module (`core::error` / `core::net`) as unstable or stable in a later version than the items the module contains.

Previously, rustdoc would always show the *stability as declared* for an item rather than the *stability as publicly reachable* (i.e. the features required to actually access the item), which could be confusing when viewing the docs. This PR changes it so that we show the stability of the first unstable parent or the most recently stabilized parent instead, to hopefully make things less confusing.

fixes https://github.com/rust-lang/rust/issues/130765

screenshots:
![error in std](https://github.com/user-attachments/assets/2ab9bdb9-ed81-4e45-a832-ac7d3ba1be3f) ![error in core](https://github.com/user-attachments/assets/46f46182-5642-4ac5-b92e-0b99a8e2496d)

compiler/rustc_attr/src/builtin.rs

@@ -153,7 +153,7 @@ pub enum StabilityLevel {
 }
 
 /// Rust release in which a feature is stabilized.
-#[derive(Encodable, Decodable, PartialEq, Copy, Clone, Debug, Eq, Hash)]
+#[derive(Encodable, Decodable, PartialEq, Copy, Clone, Debug, Eq, PartialOrd, Ord, Hash)]
 #[derive(HashStable_Generic)]
 pub enum StableSince {
     Version(RustcVersion),

src/librustdoc/clean/types.rs

@@ -384,7 +384,45 @@ fn is_field_vis_inherited(tcx: TyCtxt<'_>, def_id: DefId) -> bool {
 
 impl Item {
     pub(crate) fn stability(&self, tcx: TyCtxt<'_>) -> Option<Stability> {
-        self.def_id().and_then(|did| tcx.lookup_stability(did))
+        let (mut def_id, mut stability) = if let Some(inlined) = self.inline_stmt_id {
+            let inlined_def_id = inlined.to_def_id();
+            if let Some(stability) = tcx.lookup_stability(inlined_def_id) {
+                (inlined_def_id, stability)
+            } else {
+                // For re-exports into crates without `staged_api`, reuse the original stability.
+                // This is necessary, because we always want to mark unstable items.
+                let def_id = self.def_id()?;
+                return tcx.lookup_stability(def_id);
+            }
+        } else {
+            let def_id = self.def_id()?;
+            let stability = tcx.lookup_stability(def_id)?;
+            (def_id, stability)
+        };
+
+        let StabilityLevel::Stable { mut since, allowed_through_unstable_modules: false } =
+            stability.level
+        else {
+            return Some(stability);
+        };
+
+        // If any of the item's ancestors was stabilized later or is still unstable,
+        // then report the ancestor's stability instead.
+        while let Some(parent_def_id) = tcx.opt_parent(def_id) {
+            if let Some(parent_stability) = tcx.lookup_stability(parent_def_id) {
+                match parent_stability.level {
+                    StabilityLevel::Unstable { .. } => return Some(parent_stability),
+                    StabilityLevel::Stable { since: parent_since, .. } => {
+                        if parent_since > since {
+                            stability = parent_stability;
+                            since = parent_since;
+                        }
+                    }
+                }
+            }
+            def_id = parent_def_id;
+        }
+        Some(stability)
     }
 
     pub(crate) fn const_stability(&self, tcx: TyCtxt<'_>) -> Option<ConstStability> {

tests/rustdoc/const-display.rs

@@ -1,8 +1,6 @@
 #![crate_name = "foo"]
 
-#![unstable(feature = "humans",
+#![stable(feature = "rust1", since = "1.0.0")]
-            reason = "who ever let humans program computers, we're apparently really bad at it",
-            issue = "none")]
 
 #![feature(foo, foo2)]
 #![feature(staged_api)]
@@ -48,10 +46,18 @@ pub const unsafe fn foo2_gated() -> u32 { 42 }
 #[rustc_const_stable(feature = "rust1", since = "1.0.0")]
 pub const unsafe fn bar2_gated() -> u32 { 42 }
 
-//@ has 'foo/fn.bar_not_gated.html' '//pre' 'pub const unsafe fn bar_not_gated() -> u32'
+#[unstable(
-//@ !hasraw - '//span[@class="since"]'
+    feature = "humans",
-pub const unsafe fn bar_not_gated() -> u32 { 42 }
+    reason = "who ever let humans program computers, we're apparently really bad at it",
+    issue = "none",
+)]
+pub mod unstable {
+    //@ has 'foo/unstable/fn.bar_not_gated.html' '//pre' 'pub const unsafe fn bar_not_gated() -> u32'
+    //@ !hasraw - '//span[@class="since"]'
+    pub const unsafe fn bar_not_gated() -> u32 { 42 }
+}
 
+#[stable(feature = "rust1", since = "1.0.0")]
 pub struct Foo;
 
 impl Foo {

tests/rustdoc/stability.rs

@@ -1,6 +1,6 @@
 #![feature(staged_api)]
 
-#![unstable(feature = "test", issue = "none")]
+#![stable(feature = "rust1", since = "1.0.0")]
 
 //@ has stability/index.html
 //@ has - '//ul[@class="item-table"]/li[1]//a' AaStable
@@ -10,6 +10,7 @@
 #[stable(feature = "rust2", since = "2.2.2")]
 pub struct AaStable;
 
+#[unstable(feature = "test", issue = "none")]
 pub struct Unstable {
     //@ has stability/struct.Unstable.html \
     //      '//span[@class="item-info"]//div[@class="stab unstable"]' \
@@ -21,3 +22,31 @@ pub struct Unstable {
 
 #[stable(feature = "rust2", since = "2.2.2")]
 pub struct ZzStable;
+
+#[unstable(feature = "unstable", issue = "none")]
+pub mod unstable {
+    //@ !hasraw stability/unstable/struct.Foo.html '//span[@class="since"]'
+    //@ has - '//div[@class="stab unstable"]' 'experimental'
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub struct Foo;
+}
+
+#[stable(feature = "rust2", since = "2.2.2")]
+pub mod stable_later {
+    //@ has stability/stable_later/struct.Bar.html '//span[@class="since"]' '2.2.2'
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub struct Bar;
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+pub mod stable_earlier {
+    //@ has stability/stable_earlier/struct.Foo.html '//span[@class="since"]' '1.0.0'
+    #[doc(inline)]
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub use crate::unstable::Foo;
+
+    //@ has stability/stable_earlier/struct.Bar.html '//span[@class="since"]' '1.0.0'
+    #[doc(inline)]
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub use crate::stable_later::Bar;
+}