rustdoc: hide #[repr(...)] if it isn't part of the public ABI

Author: fmease

src/doc/rustdoc/src/advanced-features.md

@@ -89,7 +89,13 @@ https://doc.rust-lang.org/stable/std/?search=%s&go_to_first=true
 This URL adds the `go_to_first=true` query parameter which can be appended to any `rustdoc` search URL
 to automatically go to the first result.
 
-## `#[repr(transparent)]`: Documenting the transparent representation
+## `#[repr(...)]`: Documenting the representation of a type
+
+Generally, rustdoc only displays the representation of a given type if none of its variants are
+`#[doc(hidden)]` and if all of its fields are public and not `#[doc(hidden)]` since it's likely not
+meant to be considered part of the public ABI otherwise.
+
+### `#[repr(transparent)]`
 
 You can read more about `#[repr(transparent)]` itself in the [Rust Reference][repr-trans-ref] and
 in the [Rustonomicon][repr-trans-nomicon].
@@ -102,7 +108,7 @@ fields are 1-ZST fields. The term *1-ZST* refers to types that are one-aligned a
 It would seem that one can manually hide the attribute with `#[cfg_attr(not(doc), repr(transparent))]`
 if one wishes to declare the representation as private even if the non-1-ZST field is public.
 However, due to [current limitations][cross-crate-cfg-doc], this method is not always guaranteed to work.
-Therefore, if you would like to do so, you should always write it down in prose independently of whether
+Therefore, if you would like to do so, you should always write that down in prose independently of whether
 you use `cfg_attr` or not.
 
 [repr-trans-ref]: https://doc.rust-lang.org/reference/type-layout.html#the-transparent-representation

src/librustdoc/clean/types.rs

@@ -1,3 +1,4 @@
+use std::borrow::Cow;
 use std::hash::Hash;
 use std::path::PathBuf;
 use std::sync::{Arc, OnceLock as OnceCell};
@@ -763,9 +764,7 @@ impl Item {
         const ALLOWED_ATTRIBUTES: &[Symbol] =
             &[sym::export_name, sym::link_section, sym::no_mangle, sym::non_exhaustive];
 
-        use rustc_abi::IntegerType;
-
-        let mut attrs: Vec<String> = self
+        let mut attrs: Vec<_> = self
             .attrs
             .other_attrs
             .iter()
@@ -805,69 +804,103 @@ impl Item {
             })
             .collect();
 
-        // Add #[repr(...)]
-        if let Some(def_id) = self.def_id()
-            && let ItemType::Struct | ItemType::Enum | ItemType::Union = self.type_()
+        if let Some(repr) = self.repr(tcx, cache) {
+            attrs.push(repr);
+        }
+
+        attrs
+    }
+
+    /// Compute the *public* `#[repr]` of this item.
+    ///
+    /// Read more about it here:
+    /// https://doc.rust-lang.org/nightly/rustdoc/advanced-features.html#repr-documenting-the-representation-of-a-type
+    fn repr<'tcx>(&self, tcx: TyCtxt<'tcx>, cache: &Cache) -> Option<String> {
+        let def_id = self.def_id()?;
+        let (ItemType::Struct | ItemType::Enum | ItemType::Union) = self.type_() else {
+            return None;
+        };
+        let adt = tcx.adt_def(def_id);
+        let repr = adt.repr();
+
+        let is_visible = |def_id| cache.document_hidden || !tcx.is_doc_hidden(def_id);
+        let is_field_public = |field: &'tcx ty::FieldDef| {
+            (cache.document_private || field.vis.is_public()) && is_visible(field.did)
+        };
+
+        if repr.transparent() {
+            // `repr(transparent)` can only be applied to structs and one-variant enums.
+            let var = adt.variant(rustc_abi::FIRST_VARIANT);
+            // `repr(transparent)` is public iff the non-1-ZST field is public or
+            // at least one field is public in case all fields are 1-ZST fields.
+            let is_public = is_visible(var.def_id)
+                && var
+                    .fields
+                    .iter()
+                    .find(|field| {
+                        let ty = field.ty(tcx, ty::GenericArgs::identity_for_item(tcx, field.did));
+                        tcx.layout_of(
+                            ty::TypingEnv::post_analysis(tcx, field.did).as_query_input(ty),
+                        )
+                        .is_ok_and(|layout| !layout.is_1zst())
+                    })
+                    .map_or_else(
+                        || var.fields.is_empty() || var.fields.iter().any(is_field_public),
+                        is_field_public,
+                    );
+
+            // Since `repr(transparent)` can't have any other reprs or
+            // repr modifiers beside it, we can safely return early here.
+            return is_public.then(|| "#[repr(transparent)]".into());
+        }
+
+        // Fast path which avoids looking through the variants and fields in
+        // the common case of no `#[repr]` or in the case of `#[repr(Rust)]`.
+        // FIXME: This check is not forward compatible!
+        if !repr.c()
+            && !repr.simd()
+            && repr.int.is_none()
+            && repr.pack.is_none()
+            && repr.align.is_none()
         {
-            let adt = tcx.adt_def(def_id);
-            let repr = adt.repr();
-            let mut out = Vec::new();
-            if repr.c() {
-                out.push("C");
-            }
-            if repr.transparent() {
-                // Render `repr(transparent)` iff the non-1-ZST field is public or at least one
-                // field is public in case all fields are 1-ZST fields.
-                let render_transparent = cache.document_private
-                    || adt
-                        .all_fields()
-                        .find(|field| {
-                            let ty =
-                                field.ty(tcx, ty::GenericArgs::identity_for_item(tcx, field.did));
-                            tcx.layout_of(
-                                ty::TypingEnv::post_analysis(tcx, field.did).as_query_input(ty),
-                            )
-                            .is_ok_and(|layout| !layout.is_1zst())
-                        })
-                        .map_or_else(
-                            || adt.all_fields().any(|field| field.vis.is_public()),
-                            |field| field.vis.is_public(),
-                        );
+            return None;
+        }
 
-                if render_transparent {
-                    out.push("transparent");
+        let is_public = adt.variants().iter().all(|variant| {
+            is_visible(variant.def_id) && variant.fields.iter().all(is_field_public)
+        });
+        if !is_public {
+            return None;
+        }
+
+        let mut result = Vec::<Cow<'_, _>>::new();
+
+        if repr.c() {
+            result.push("C".into());
+        }
+        if repr.simd() {
+            result.push("simd".into());
+        }
+        if let Some(int) = repr.int {
+            let prefix = if int.is_signed() { 'i' } else { 'u' };
+            let int = match int {
+                rustc_abi::IntegerType::Pointer(_) => format!("{prefix}size"),
+                rustc_abi::IntegerType::Fixed(int, _) => {
+                    format!("{prefix}{}", int.size().bytes() * 8)
                 }
-            }
-            if repr.simd() {
-                out.push("simd");
-            }
-            let pack_s;
-            if let Some(pack) = repr.pack {
-                pack_s = format!("packed({})", pack.bytes());
-                out.push(&pack_s);
-            }
-            let align_s;
-            if let Some(align) = repr.align {
-                align_s = format!("align({})", align.bytes());
-                out.push(&align_s);
-            }
-            let int_s;
-            if let Some(int) = repr.int {
-                int_s = match int {
-                    IntegerType::Pointer(is_signed) => {
-                        format!("{}size", if is_signed { 'i' } else { 'u' })
-                    }
-                    IntegerType::Fixed(size, is_signed) => {
-                        format!("{}{}", if is_signed { 'i' } else { 'u' }, size.size().bytes() * 8)
-                    }
-                };
-                out.push(&int_s);
-            }
-            if !out.is_empty() {
-                attrs.push(format!("#[repr({})]", out.join(", ")));
-            }
+            };
+            result.push(int.into());
         }
-        attrs
+
+        // Render modifiers last.
+        if let Some(pack) = repr.pack {
+            result.push(format!("packed({})", pack.bytes()).into());
+        }
+        if let Some(align) = repr.align {
+            result.push(format!("align({})", align.bytes()).into());
+        }
+
+        (!result.is_empty()).then(|| format!("#[repr({})]", result.join(", ")))
     }
 
     pub fn is_doc_hidden(&self) -> bool {

tests/rustdoc-gui/src/test_docs/lib.rs

@@ -454,10 +454,10 @@ pub fn safe_fn() {}
 
 #[repr(C)]
 pub struct WithGenerics<T: TraitWithNoDocblocks, S = String, E = WhoLetTheDogOut, P = i8> {
-    s: S,
-    t: T,
-    e: E,
-    p: P,
+    pub s: S,
+    pub t: T,
+    pub e: E,
+    pub p: P,
 }
 
 pub struct StructWithPublicUndocumentedFields {

tests/rustdoc-json/attrs/repr_align.rs

@@ -3,6 +3,6 @@
 //@ is "$.index[?(@.name=='Aligned')].attrs" '["#[repr(align(4))]"]'
 #[repr(align(4))]
 pub struct Aligned {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }

tests/rustdoc-json/attrs/repr_combination.rs

@@ -25,54 +25,54 @@ pub enum ReversedReprCUsize {
 //@ is "$.index[?(@.name=='ReprCPacked')].attrs" '["#[repr(C, packed(1))]"]'
 #[repr(C, packed)]
 pub struct ReprCPacked {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }
 
 //@ is "$.index[?(@.name=='SeparateReprCPacked')].attrs" '["#[repr(C, packed(2))]"]'
 #[repr(C)]
 #[repr(packed(2))]
 pub struct SeparateReprCPacked {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }
 
 //@ is "$.index[?(@.name=='ReversedReprCPacked')].attrs" '["#[repr(C, packed(2))]"]'
 #[repr(packed(2), C)]
 pub struct ReversedReprCPacked {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }
 
 //@ is "$.index[?(@.name=='ReprCAlign')].attrs" '["#[repr(C, align(16))]"]'
 #[repr(C, align(16))]
 pub struct ReprCAlign {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }
 
 //@ is "$.index[?(@.name=='SeparateReprCAlign')].attrs" '["#[repr(C, align(2))]"]'
 #[repr(C)]
 #[repr(align(2))]
 pub struct SeparateReprCAlign {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }
 
 //@ is "$.index[?(@.name=='ReversedReprCAlign')].attrs" '["#[repr(C, align(2))]"]'
 #[repr(align(2), C)]
 pub struct ReversedReprCAlign {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }
 
-//@ is "$.index[?(@.name=='AlignedExplicitRepr')].attrs" '["#[repr(C, align(16), isize)]"]'
+//@ is "$.index[?(@.name=='AlignedExplicitRepr')].attrs" '["#[repr(C, isize, align(16))]"]'
 #[repr(C, align(16), isize)]
 pub enum AlignedExplicitRepr {
     First,
 }
 
-//@ is "$.index[?(@.name=='ReorderedAlignedExplicitRepr')].attrs" '["#[repr(C, align(16), isize)]"]'
+//@ is "$.index[?(@.name=='ReorderedAlignedExplicitRepr')].attrs" '["#[repr(C, isize, align(16))]"]'
 #[repr(isize, C, align(16))]
 pub enum ReorderedAlignedExplicitRepr {
     First,

tests/rustdoc-json/attrs/repr_packed.rs

@@ -6,13 +6,13 @@
 //@ is "$.index[?(@.name=='Packed')].attrs" '["#[repr(packed(1))]"]'
 #[repr(packed)]
 pub struct Packed {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }
 
 //@ is "$.index[?(@.name=='PackedAligned')].attrs" '["#[repr(packed(4))]"]'
 #[repr(packed(4))]
 pub struct PackedAligned {
-    a: i8,
-    b: i64,
+    pub a: i8,
+    pub b: i64,
 }

tests/rustdoc/inline_cross/auxiliary/repr.rs

@@ -1,32 +1,66 @@
-#![feature(repr_simd)]
+#![feature(repr_simd)] // only used for the `ReprSimd` test case
 
-#[repr(C, align(8))]
+#[repr(Rust)]
+pub struct ReprRust;
+
+#[repr(C, align(8))] // **public**
 pub struct ReprC {
-    field: u8,
+    pub field: u8,
+}
+
+#[repr(C)] // private
+pub struct ReprCPrivField {
+    private: u8,
+    pub public: i8,
 }
-#[repr(simd, packed(2))]
+
+#[repr(align(4))] // private
+pub struct ReprAlignHiddenField {
+    #[doc(hidden)]
+    pub hidden: i16,
+}
+
+#[repr(simd, packed(2))] // **public**
 pub struct ReprSimd {
-    field: [u8; 1],
+    pub field: [u8; 1],
 }
-#[repr(transparent)]
+
+#[repr(transparent)] // **public**
 pub struct ReprTransparent {
-    pub field: u8,
+    pub field: u8, // non-1-ZST field
 }
-#[repr(isize)]
+
+#[repr(isize)] // **public**
 pub enum ReprIsize {
     Bla,
 }
-#[repr(u8)]
+
+#[repr(u8)] // **public**
 pub enum ReprU8 {
     Bla,
 }
 
+#[repr(u32)] // private
+pub enum ReprU32 {
+    #[doc(hidden)]
+    Hidden,
+    Public,
+}
+
+#[repr(u64)] // private
+pub enum ReprU64HiddenVariants {
+    #[doc(hidden)]
+    A,
+    #[doc(hidden)]
+    B,
+}
+
 #[repr(transparent)] // private
 pub struct ReprTransparentPrivField {
     field: u32, // non-1-ZST field
 }
 
-#[repr(transparent)] // public
+#[repr(transparent)] // **public**
 pub struct ReprTransparentPriv1ZstFields {
     marker0: Marker,
     pub main: u64, // non-1-ZST field