Skip to content

Commit 2cd93b1

Browse files
fmeasefmease
committed
rustdoc: hide #[repr(...)] if it isn't part of the public ABI
1 parent e88e854 commit 2cd93b1

File tree

7 files changed

+243
-74
lines changed

7 files changed

+243
-74
lines changed

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

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,13 @@ https://doc.rust-lang.org/stable/std/?search=%s&go_to_first=true
8989
This URL adds the `go_to_first=true` query parameter which can be appended to any `rustdoc` search URL
9090
to automatically go to the first result.
9191

92-
## `#[repr(transparent)]`: Documenting the transparent representation
92+
## `#[repr(...)]`: Documenting the representation of a type
93+
94+
Generally, rustdoc only displays the representation of a given type if none of its variants are
95+
`#[doc(hidden)]` and if all of its fields are public and not `#[doc(hidden)]` since it's likely not
96+
meant to be considered part of the public ABI otherwise.
97+
98+
### `#[repr(transparent)]`
9399

94100
You can read more about `#[repr(transparent)]` itself in the [Rust Reference][repr-trans-ref] and
95101
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
102108
It would seem that one can manually hide the attribute with `#[cfg_attr(not(doc), repr(transparent))]`
103109
if one wishes to declare the representation as private even if the non-1-ZST field is public.
104110
However, due to [current limitations][cross-crate-cfg-doc], this method is not always guaranteed to work.
105-
Therefore, if you would like to do so, you should always write it down in prose independently of whether
111+
Therefore, if you would like to do so, you should always write that down in prose independently of whether
106112
you use `cfg_attr` or not.
107113

108114
[repr-trans-ref]: https://doc.rust-lang.org/reference/type-layout.html#the-transparent-representation

‎src/librustdoc/clean/types.rs‎

Lines changed: 89 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
use std::borrow::Cow;
12
use std::hash::Hash;
23
use std::path::PathBuf;
34
use std::sync::{Arc, OnceLock as OnceCell};
@@ -765,9 +766,7 @@ impl Item {
765766
const ALLOWED_ATTRIBUTES: &[Symbol] =
766767
&[sym::export_name, sym::link_section, sym::no_mangle, sym::non_exhaustive];
767768

768-
use rustc_abi::IntegerType;
769-
770-
let mut attrs: Vec<String> = self
769+
let mut attrs: Vec<_> = self
771770
.attrs
772771
.other_attrs
773772
.iter()
@@ -798,23 +797,40 @@ impl Item {
798797
})
799798
.collect();
800799

801-
// Add #[repr(...)]
802-
if let Some(def_id) = self.def_id()
803-
&& let ItemType::Struct | ItemType::Enum | ItemType::Union = self.type_()
804-
{
805-
let adt = tcx.adt_def(def_id);
806-
let repr = adt.repr();
807-
let mut out = Vec::new();
808-
if repr.c() {
809-
out.push("C");
810-
}
811-
if repr.transparent() {
812-
// Render `repr(transparent)` iff the non-1-ZST field is public or at least one
813-
// field is public in case all fields are 1-ZST fields.
814-
let render_transparent = is_json
815-
|| cache.document_private
816-
|| adt
817-
.all_fields()
800+
if let Some(repr) = self.repr(tcx, cache, is_json) {
801+
attrs.push(repr);
802+
}
803+
804+
attrs
805+
}
806+
807+
/// Compute the *public* `#[repr]` of this item.
808+
///
809+
/// Read more about it here:
810+
/// <https://doc.rust-lang.org/nightly/rustdoc/advanced-features.html#repr-documenting-the-representation-of-a-type>.
811+
fn repr<'tcx>(&self, tcx: TyCtxt<'tcx>, cache: &Cache, is_json: bool) -> Option<String> {
812+
let def_id = self.def_id()?;
813+
let (ItemType::Struct | ItemType::Enum | ItemType::Union) = self.type_() else {
814+
return None;
815+
};
816+
let adt = tcx.adt_def(def_id);
817+
let repr = adt.repr();
818+
819+
let is_visible = |def_id| cache.document_hidden || !tcx.is_doc_hidden(def_id);
820+
let is_field_public = |field: &'tcx ty::FieldDef| {
821+
(cache.document_private || field.vis.is_public()) && is_visible(field.did)
822+
};
823+
824+
if repr.transparent() {
825+
// `repr(transparent)` can only be applied to structs and single-variant enums.
826+
let var = adt.variant(rustc_abi::FIRST_VARIANT);
827+
// `repr(transparent)` is public iff the non-1-ZST field is public or
828+
// at least one field is public in case all fields are 1-ZST fields.
829+
let is_public = is_json
830+
|| is_visible(var.def_id)
831+
&& var
832+
.fields
833+
.iter()
818834
.find(|field| {
819835
let ty =
820836
field.ty(tcx, ty::GenericArgs::identity_for_item(tcx, field.did));
@@ -824,44 +840,63 @@ impl Item {
824840
.is_ok_and(|layout| !layout.is_1zst())
825841
})
826842
.map_or_else(
827-
|| adt.all_fields().any(|field| field.vis.is_public()),
828-
|field| field.vis.is_public(),
843+
|| var.fields.is_empty() || var.fields.iter().any(is_field_public),
844+
is_field_public,
829845
);
830846

831-
if render_transparent {
832-
out.push("transparent");
847+
// Since `repr(transparent)` can't have any other reprs or
848+
// repr modifiers beside it, we can safely return early here.
849+
return is_public.then(|| "#[repr(transparent)]".into());
850+
}
851+
852+
// Fast path which avoids looking through the variants and fields in
853+
// the common case of no `#[repr]` or in the case of `#[repr(Rust)]`.
854+
// FIXME: This check is not forward compatible!
855+
if !repr.c()
856+
&& !repr.simd()
857+
&& repr.int.is_none()
858+
&& repr.pack.is_none()
859+
&& repr.align.is_none()
860+
{
861+
return None;
862+
}
863+
864+
let is_public = is_json
865+
|| adt.variants().iter().all(|variant| {
866+
is_visible(variant.def_id) && variant.fields.iter().all(is_field_public)
867+
});
868+
if !is_public {
869+
return None;
870+
}
871+
872+
let mut result = Vec::<Cow<'_, _>>::new();
873+
874+
if repr.c() {
875+
result.push("C".into());
876+
}
877+
if repr.simd() {
878+
result.push("simd".into());
879+
}
880+
if let Some(int) = repr.int {
881+
let prefix = if int.is_signed() { 'i' } else { 'u' };
882+
let int = match int {
883+
rustc_abi::IntegerType::Pointer(_) => format!("{prefix}size"),
884+
rustc_abi::IntegerType::Fixed(int, _) => {
885+
format!("{prefix}{}", int.size().bytes() * 8)
833886
}
834-
}
835-
if repr.simd() {
836-
out.push("simd");
837-
}
838-
let pack_s;
839-
if let Some(pack) = repr.pack {
840-
pack_s = format!("packed({})", pack.bytes());
841-
out.push(&pack_s);
842-
}
843-
let align_s;
844-
if let Some(align) = repr.align {
845-
align_s = format!("align({})", align.bytes());
846-
out.push(&align_s);
847-
}
848-
let int_s;
849-
if let Some(int) = repr.int {
850-
int_s = match int {
851-
IntegerType::Pointer(is_signed) => {
852-
format!("{}size", if is_signed { 'i' } else { 'u' })
853-
}
854-
IntegerType::Fixed(size, is_signed) => {
855-
format!("{}{}", if is_signed { 'i' } else { 'u' }, size.size().bytes() * 8)
856-
}
857-
};
858-
out.push(&int_s);
859-
}
860-
if !out.is_empty() {
861-
attrs.push(format!("#[repr({})]", out.join(", ")));
862-
}
887+
};
888+
result.push(int.into());
863889
}
864-
attrs
890+
891+
// Render modifiers last.
892+
if let Some(pack) = repr.pack {
893+
result.push(format!("packed({})", pack.bytes()).into());
894+
}
895+
if let Some(align) = repr.align {
896+
result.push(format!("align({})", align.bytes()).into());
897+
}
898+
899+
(!result.is_empty()).then(|| format!("#[repr({})]", result.join(", ")))
865900
}
866901

867902
pub fn is_doc_hidden(&self) -> bool {

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -455,10 +455,10 @@ pub fn safe_fn() {}
455455

456456
#[repr(C)]
457457
pub struct WithGenerics<T: TraitWithNoDocblocks, S = String, E = WhoLetTheDogOut, P = i8> {
458-
s: S,
459-
t: T,
460-
e: E,
461-
p: P,
458+
pub s: S,
459+
pub t: T,
460+
pub e: E,
461+
pub p: P,
462462
}
463463

464464
pub struct StructWithPublicUndocumentedFields {

‎tests/rustdoc-json/attrs/repr_combination.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,13 +66,13 @@ pub struct ReversedReprCAlign {
6666
b: i64,
6767
}
6868

69-
//@ is "$.index[?(@.name=='AlignedExplicitRepr')].attrs" '["#[repr(C, align(16), isize)]"]'
69+
//@ is "$.index[?(@.name=='AlignedExplicitRepr')].attrs" '["#[repr(C, isize, align(16))]"]'
7070
#[repr(C, align(16), isize)]
7171
pub enum AlignedExplicitRepr {
7272
First,
7373
}
7474

75-
//@ is "$.index[?(@.name=='ReorderedAlignedExplicitRepr')].attrs" '["#[repr(C, align(16), isize)]"]'
75+
//@ is "$.index[?(@.name=='ReorderedAlignedExplicitRepr')].attrs" '["#[repr(C, isize, align(16))]"]'
7676
#[repr(isize, C, align(16))]
7777
pub enum ReorderedAlignedExplicitRepr {
7878
First,

‎tests/rustdoc/inline_cross/auxiliary/repr.rs‎

Lines changed: 44 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,66 @@
1-
#![feature(repr_simd)]
1+
#![feature(repr_simd)] // only used for the `ReprSimd` test case
22

3-
#[repr(C, align(8))]
3+
#[repr(Rust)]
4+
pub struct ReprRust;
5+
6+
#[repr(C, align(8))] // **public**
47
pub struct ReprC {
5-
field: u8,
8+
pub field: u8,
9+
}
10+
11+
#[repr(C)] // private
12+
pub struct ReprCPrivField {
13+
private: u8,
14+
pub public: i8,
615
}
7-
#[repr(simd, packed(2))]
16+
17+
#[repr(align(4))] // private
18+
pub struct ReprAlignHiddenField {
19+
#[doc(hidden)]
20+
pub hidden: i16,
21+
}
22+
23+
#[repr(simd, packed(2))] // **public**
824
pub struct ReprSimd {
9-
field: [u8; 1],
25+
pub field: [u8; 1],
1026
}
11-
#[repr(transparent)]
27+
28+
#[repr(transparent)] // **public**
1229
pub struct ReprTransparent {
13-
pub field: u8,
30+
pub field: u8, // non-1-ZST field
1431
}
15-
#[repr(isize)]
32+
33+
#[repr(isize)] // **public**
1634
pub enum ReprIsize {
1735
Bla,
1836
}
19-
#[repr(u8)]
37+
38+
#[repr(u8)] // **public**
2039
pub enum ReprU8 {
2140
Bla,
2241
}
2342

43+
#[repr(u32)] // private
44+
pub enum ReprU32 {
45+
#[doc(hidden)]
46+
Hidden,
47+
Public,
48+
}
49+
50+
#[repr(u64)] // private
51+
pub enum ReprU64HiddenVariants {
52+
#[doc(hidden)]
53+
A,
54+
#[doc(hidden)]
55+
B,
56+
}
57+
2458
#[repr(transparent)] // private
2559
pub struct ReprTransparentPrivField {
2660
field: u32, // non-1-ZST field
2761
}
2862

29-
#[repr(transparent)] // public
63+
#[repr(transparent)] // **public**
3064
pub struct ReprTransparentPriv1ZstFields {
3165
marker0: Marker,
3266
pub main: u64, // non-1-ZST field

‎tests/rustdoc/inline_cross/repr.rs‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,22 +7,47 @@
77

88
extern crate repr;
99

10+
// Never display `repr(Rust)` since it's the default anyway.
11+
//@ has 'foo/struct.ReprRust.html'
12+
//@ !has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(Rust)]'
13+
pub use repr::ReprRust;
14+
1015
//@ has 'foo/struct.ReprC.html'
1116
//@ has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(C, align(8))]'
1217
pub use repr::ReprC;
18+
19+
//@ has 'foo/struct.ReprCPrivField.html'
20+
//@ !has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(C)]'
21+
pub use repr::ReprCPrivField;
22+
23+
//@ has 'foo/struct.ReprAlignHiddenField.html'
24+
//@ !has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(align(4))]'
25+
pub use repr::ReprAlignHiddenField;
26+
1327
//@ has 'foo/struct.ReprSimd.html'
1428
//@ has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(simd, packed(2))]'
1529
pub use repr::ReprSimd;
30+
1631
//@ has 'foo/struct.ReprTransparent.html'
1732
//@ has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(transparent)]'
1833
pub use repr::ReprTransparent;
34+
1935
//@ has 'foo/enum.ReprIsize.html'
2036
//@ has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(isize)]'
2137
pub use repr::ReprIsize;
38+
2239
//@ has 'foo/enum.ReprU8.html'
2340
//@ has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(u8)]'
2441
pub use repr::ReprU8;
2542

43+
//@ has 'foo/enum.ReprU32.html'
44+
//@ !has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(u32)]'
45+
pub use repr::ReprU32;
46+
47+
//@ has 'foo/enum.ReprU64HiddenVariants.html'
48+
//@ !has - '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[repr(u64)]'
49+
pub use repr::ReprU64HiddenVariants;
50+
2651
// Regression test for <https://github.com/rust-lang/rust/issues/90435>.
2752
// Check that we show `#[repr(transparent)]` iff the non-1-ZST field is public or at least one
2853
// field is public in case all fields are 1-ZST fields.

0 commit comments

Comments
 (0)