rustdoc: support multiple unstable attributes

Author: dianne

compiler/rustc_attr/src/builtin.rs

@@ -89,6 +89,10 @@ impl Stability {
     pub fn unstable_features(&self) -> impl Iterator<Item = Symbol> + use<'_> {
         self.level.unstable_features()
     }
+
+    pub fn is_rustc_private(&self) -> bool {
+        self.level.has_unstable_feature(sym::rustc_private)
+    }
 }
 
 /// Represents the `#[rustc_const_unstable]` and `#[rustc_const_stable]` attributes.

src/librustdoc/clean/inline.rs

@@ -438,10 +438,8 @@ pub(crate) fn build_impl(
     let associated_trait = tcx.impl_trait_ref(did).map(ty::EarlyBinder::skip_binder);
 
     // Do not inline compiler-internal items unless we're a compiler-internal crate.
-    let is_compiler_internal = |did| {
-        tcx.lookup_stability(did)
-            .is_some_and(|stab| stab.is_unstable() && stab.feature == sym::rustc_private)
-    };
+    let is_compiler_internal =
+        |did| tcx.lookup_stability(did).is_some_and(|stab| stab.is_rustc_private());
     let document_compiler_internal = is_compiler_internal(LOCAL_CRATE.as_def_id());
     let is_directly_public = |cx: &mut DocContext<'_>, did| {
         cx.cache.effective_visibilities.is_directly_public(tcx, did)

src/librustdoc/clean/types.rs

@@ -386,8 +386,8 @@ impl Item {
     /// Returns the effective stability of the item.
     ///
     /// This method should only be called after the `propagate-stability` pass has been run.
-    pub(crate) fn stability(&self, tcx: TyCtxt<'_>) -> Option<Stability> {
-        let stability = self.inner.stability;
+    pub(crate) fn stability(&self, tcx: TyCtxt<'_>) -> Option<&Stability> {
+        let stability = self.inner.stability.as_ref();
         debug_assert!(
             stability.is_some()
                 || self.def_id().is_none_or(|did| tcx.lookup_stability(did).is_none()),
@@ -396,7 +396,7 @@ impl Item {
         stability
     }
 
-    pub(crate) fn const_stability(&self, tcx: TyCtxt<'_>) -> Option<ConstStability> {
+    pub(crate) fn const_stability<'tcx>(&self, tcx: TyCtxt<'tcx>) -> Option<&'tcx ConstStability> {
         self.def_id().and_then(|did| tcx.lookup_const_stability(did))
     }
 

src/librustdoc/html/format.rs

@@ -13,7 +13,7 @@ use std::fmt::{self, Display, Write};
 use std::iter::{self, once};
 
 use itertools::Itertools;
-use rustc_attr::{ConstStability, StabilityLevel, StableSince};
+use rustc_attr::{ConstStability, ConstStabilityLevel, StableSince};
 use rustc_data_structures::captures::Captures;
 use rustc_data_structures::fx::FxHashSet;
 use rustc_hir::def::DefKind;
@@ -1693,20 +1693,24 @@ impl PrintWithSpace for hir::Mutability {
 pub(crate) fn print_constness_with_space(
     c: &hir::Constness,
     overall_stab: Option<StableSince>,
-    const_stab: Option<ConstStability>,
+    const_stab: Option<&ConstStability>,
 ) -> &'static str {
     match c {
         hir::Constness::Const => match (overall_stab, const_stab) {
             // const stable...
-            (_, Some(ConstStability { level: StabilityLevel::Stable { .. }, .. }))
+            (_, Some(ConstStability { level: ConstStabilityLevel::Stable { .. }, .. }))
             // ...or when feature(staged_api) is not set...
             | (_, None)
-            // ...or when const unstable, but overall unstable too
-            | (None, Some(ConstStability { level: StabilityLevel::Unstable { .. }, .. })) => {
+            // ...or when const unstable, but overall unstable too...
+            | (None, Some(ConstStability { level: ConstStabilityLevel::Unstable { .. }, .. }))
+            // ...or when a const stability level was not explicitly provided, and overall unstable
+            | (None, Some(ConstStability { level: ConstStabilityLevel::Implicit, .. })) => {
                 "const "
             }
-            // const unstable (and overall stable)
-            (Some(_), Some(ConstStability { level: StabilityLevel::Unstable { .. }, .. })) => "",
+            // const unstable (and overall stable)...
+            (Some(_), Some(ConstStability { level: ConstStabilityLevel::Unstable { .. }, .. }))
+            // ...or without an explicit const stability level (and overall stable)
+            | (Some(_), Some(ConstStability { level: ConstStabilityLevel::Implicit, .. })) => "",
         },
         // not const
         hir::Constness::NotConst => "",

src/librustdoc/html/render/mod.rs

@@ -45,15 +45,17 @@ use std::rc::Rc;
 use std::{fs, str};
 
 use rinja::Template;
-use rustc_attr::{ConstStability, DeprecatedSince, Deprecation, StabilityLevel, StableSince};
+use rustc_attr::{
+    ConstStability, ConstStabilityLevel, DeprecatedSince, Deprecation, StabilityLevel, StableSince,
+};
 use rustc_data_structures::captures::Captures;
 use rustc_data_structures::fx::{FxHashSet, FxIndexMap, FxIndexSet};
 use rustc_hir::Mutability;
 use rustc_hir::def_id::{DefId, DefIdSet};
 use rustc_middle::ty::print::PrintTraitRefExt;
 use rustc_middle::ty::{self, TyCtxt};
 use rustc_session::RustcVersion;
-use rustc_span::symbol::{Symbol, sym};
+use rustc_span::symbol::Symbol;
 use rustc_span::{BytePos, DUMMY_SP, FileName, RealFileName};
 use serde::ser::SerializeMap;
 use serde::{Serialize, Serializer};
@@ -674,17 +676,23 @@ enum ShortItemInfo {
     Deprecation {
         message: String,
     },
-    /// The feature corresponding to an unstable item, and optionally
-    /// a tracking issue URL and number.
+    /// The features corresponding to an unstable item, and optionally
+    /// a tracking issue URL and number for each.
     Unstable {
-        feature: String,
-        tracking: Option<(String, u32)>,
+        features: Vec<UnstableFeature>,
     },
     Portability {
         message: String,
     },
 }
 
+#[derive(Template)]
+#[template(path = "unstable_feature.html")]
+struct UnstableFeature {
+    feature: String,
+    tracking: Option<(String, u32)>,
+}
+
 /// Render the stability, deprecation and portability information that is displayed at the top of
 /// the item's documentation.
 fn short_item_info(
@@ -723,19 +731,24 @@ fn short_item_info(
 
     // Render unstable items. But don't render "rustc_private" crates (internal compiler crates).
     // Those crates are permanently unstable so it makes no sense to render "unstable" everywhere.
-    if let Some((StabilityLevel::Unstable { reason: _, issue, .. }, feature)) = item
+    if let Some(StabilityLevel::Unstable { unstables, .. }) = item
         .stability(cx.tcx())
         .as_ref()
-        .filter(|stab| stab.feature != sym::rustc_private)
-        .map(|stab| (stab.level, stab.feature))
+        .filter(|stab| !stab.is_rustc_private())
+        .map(|stab| &stab.level)
     {
-        let tracking = if let (Some(url), Some(issue)) = (&cx.shared.issue_tracker_base_url, issue)
-        {
-            Some((url.clone(), issue.get()))
-        } else {
-            None
+        let track = |issue: Option<std::num::NonZero<u32>>| {
+            if let (Some(url), Some(issue)) = (&cx.shared.issue_tracker_base_url, issue) {
+                Some((url.clone(), issue.get()))
+            } else {
+                None
+            }
         };
-        extra_info.push(ShortItemInfo::Unstable { feature: feature.to_string(), tracking });
+        let features = unstables
+            .iter()
+            .map(|u| UnstableFeature { feature: u.feature.to_string(), tracking: track(u.issue) })
+            .collect();
+        extra_info.push(ShortItemInfo::Unstable { features });
     }
 
     if let Some(message) = portability(item, parent) {
@@ -989,7 +1002,7 @@ fn assoc_method(
 fn render_stability_since_raw_with_extra(
     w: &mut Buffer,
     stable_version: Option<StableSince>,
-    const_stability: Option<ConstStability>,
+    const_stability: Option<&ConstStability>,
     extra_class: &str,
 ) -> bool {
     let mut title = String::new();
@@ -1001,18 +1014,20 @@ fn render_stability_since_raw_with_extra(
     }
 
     let const_title_and_stability = match const_stability {
-        Some(ConstStability { level: StabilityLevel::Stable { since, .. }, .. }) => {
+        Some(ConstStability { level: ConstStabilityLevel::Stable { since, .. }, .. }) => {
             since_to_string(&since)
                 .map(|since| (format!("const since {since}"), format!("const: {since}")))
         }
-        Some(ConstStability { level: StabilityLevel::Unstable { issue, .. }, feature, .. }) => {
+        Some(ConstStability { level: ConstStabilityLevel::Unstable { unstables, .. }, .. }) => {
             if stable_version.is_none() {
                 // don't display const unstable if entirely unstable
                 None
             } else {
-                let unstable = if let Some(n) = issue
-                    && let Some(feature) = feature
-                {
+                // if constness depends on multiple unstable features, only link to the first
+                // tracking issue found, to save space. the issue description should link to issues
+                // for any features it can intersect with
+                let feature_issue = unstables.iter().find_map(|u| u.issue.map(|n| (u.feature, n)));
+                let unstable = if let Some((feature, n)) = feature_issue {
                     format!(
                         "<a \
                         href=\"https://github.com/rust-lang/rust/issues/{n}\" \
@@ -1026,6 +1041,14 @@ fn render_stability_since_raw_with_extra(
                 Some((String::from("const unstable"), format!("const: {unstable}")))
             }
         }
+        Some(ConstStability { level: ConstStabilityLevel::Implicit, .. }) => {
+            // No explicit const-stability annotation was provided. Treat it as const-unstable.
+            if stable_version.is_none() {
+                None
+            } else {
+                Some((String::from("const unstable"), format!("const: unstable")))
+            }
+        }
         _ => None,
     };
 
@@ -1062,7 +1085,7 @@ fn since_to_string(since: &StableSince) -> Option<String> {
 fn render_stability_since_raw(
     w: &mut Buffer,
     ver: Option<StableSince>,
-    const_stability: Option<ConstStability>,
+    const_stability: Option<&ConstStability>,
 ) -> bool {
     render_stability_since_raw_with_extra(w, ver, const_stability, "")
 }

src/librustdoc/html/render/print_item.rs

@@ -13,7 +13,7 @@ use rustc_hir::def_id::DefId;
 use rustc_index::IndexVec;
 use rustc_middle::ty::{self, TyCtxt};
 use rustc_span::hygiene::MacroKind;
-use rustc_span::symbol::{Symbol, kw, sym};
+use rustc_span::symbol::{Symbol, kw};
 use rustc_target::abi::VariantIdx;
 use tracing::{debug, info};
 
@@ -568,7 +568,7 @@ fn extra_info_tags<'a, 'tcx: 'a>(
         // to render "unstable" everywhere.
         let stability = import_def_id
             .map_or_else(|| item.stability(tcx), |import_did| tcx.lookup_stability(import_did));
-        if stability.is_some_and(|s| s.is_unstable() && s.feature != sym::rustc_private) {
+        if stability.is_some_and(|s| s.is_unstable() && !s.is_rustc_private()) {
             write!(f, "{}", tag_html("unstable", "", "Experimental"))?;
         }
 

src/librustdoc/html/templates/short_item_info.html

@@ -4,18 +4,11 @@
             <span class="emoji">👎</span> {# #}
             <span>{{message|safe}}</span> {# #}
         </div>
-    {% when Self::Unstable with { feature, tracking } %}
+    {% when Self::Unstable with { features } %}
         <div class="stab unstable"> {# #}
             <span class="emoji">🔬</span> {# #}
             <span> {# #}
-                This is a nightly-only experimental API. ({# #}
-                <code>{{feature}}</code>
-                {% match tracking %}
-                    {% when Some with ((url, num)) %}
-                        &nbsp;<a href="{{url}}{{num}}">#{{num}}</a>
-                    {% when None %}
-                {% endmatch %}
-                ) {# #}
+                This is a nightly-only experimental API. ({{features|join(", ")|safe}}) {# #}
             </span> {# #}
         </div>
     {% when Self::Portability with { message } %}

src/librustdoc/html/templates/unstable_feature.html

@@ -0,0 +1,6 @@
+<code>{{feature}}</code>
+{% match tracking %}
+    {% when Some with ((url, num)) %}
+        &nbsp;<a href="{{url}}{{num}}">#{{num}}</a>
+    {% when None %}
+{% endmatch %}

src/librustdoc/passes/propagate_stability.rs

@@ -22,7 +22,7 @@ pub(crate) const PROPAGATE_STABILITY: Pass = Pass {
 
 pub(crate) fn propagate_stability(cr: Crate, cx: &mut DocContext<'_>) -> Crate {
     let crate_stability = cx.tcx.lookup_stability(CRATE_DEF_ID);
-    StabilityPropagator { parent_stability: crate_stability, cx }.fold_crate(cr)
+    StabilityPropagator { parent_stability: crate_stability.cloned(), cx }.fold_crate(cr)
 }
 
 struct StabilityPropagator<'a, 'tcx> {
@@ -32,28 +32,29 @@ struct StabilityPropagator<'a, 'tcx> {
 
 impl<'a, 'tcx> DocFolder for StabilityPropagator<'a, 'tcx> {
     fn fold_item(&mut self, mut item: Item) -> Option<Item> {
-        let parent_stability = self.parent_stability;
+        let parent_stability = self.parent_stability.clone();
 
         let stability = match item.item_id {
             ItemId::DefId(def_id) => {
                 let own_stability = self.cx.tcx.lookup_stability(def_id);
 
                 // If any of the item's parents was stabilized later or is still unstable,
                 // then use the parent's stability instead.
-                if let Some(own_stab) = own_stability
+                if let Some(ref own_stab) = own_stability
                     && let StabilityLevel::Stable {
                         since: own_since,
                         allowed_through_unstable_modules: false,
+                        ..
                     } = own_stab.level
-                    && let Some(parent_stab) = parent_stability
+                    && let Some(ref parent_stab) = parent_stability
                     && (parent_stab.is_unstable()
                         || parent_stab
                             .stable_since()
                             .is_some_and(|parent_since| parent_since > own_since))
                 {
-                    parent_stability
+                    parent_stability.clone()
                 } else {
-                    own_stability
+                    own_stability.cloned()
                 }
             }
             ItemId::Auto { .. } | ItemId::Blanket { .. } => {
@@ -62,7 +63,7 @@ impl<'a, 'tcx> DocFolder for StabilityPropagator<'a, 'tcx> {
             }
         };
 
-        item.inner.stability = stability;
+        item.inner.stability = stability.clone();
         self.parent_stability = stability;
         let item = self.fold_item_recur(item);
         self.parent_stability = parent_stability;

tests/rustdoc/stability.rs

@@ -83,3 +83,11 @@ pub mod stable_earlier {
     #[stable(feature = "rust1", since = "1.0.0")]
     pub use crate::stable_later::stable_in_later;
 }
+
+#[unstable(feature = "test", issue = "none")]
+#[unstable(feature = "test2", issue = "none")]
+pub trait UnstableTrait {
+    //@ has stability/trait.UnstableTrait.html \
+    //      '//span[@class="item-info"]//div[@class="stab unstable"]' \
+    //      'This is a nightly-only experimental API. (test, test2)'
+}