Skip to content

Commit 16e731a

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

File tree

8 files changed

+243
-113
lines changed

8 files changed

+243
-113
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 & 56 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};
@@ -763,9 +764,7 @@ impl Item {
763764
const ALLOWED_ATTRIBUTES: &[Symbol] =
764765
&[sym::export_name, sym::link_section, sym::no_mangle, sym::non_exhaustive];
765766

766-
use rustc_abi::IntegerType;
767-
768-
let mut attrs: Vec<String> = self
767+
let mut attrs: Vec<_> = self
769768
.attrs
770769
.other_attrs
771770
.iter()
@@ -781,9 +780,6 @@ impl Item {
781780
..,
782781
)) => {
783782
// We have separate pretty-printing logic for `#[repr(..)]` attributes.
784-
// For example, there are circumstances where `#[repr(transparent)]`
785-
// is applied but should not be publicly shown in rustdoc
786-
// because it isn't public API.
787783
None
788784
}
789785
_ => Some({
@@ -805,22 +801,40 @@ impl Item {
805801
})
806802
.collect();
807803

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

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

873906
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
@@ -454,10 +454,10 @@ pub fn safe_fn() {}
454454

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

463463
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-json/attrs/repr_transparent.rs‎

Lines changed: 0 additions & 37 deletions
This file was deleted.

‎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)