Skip to content

Commit dc27ca1

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

File tree

6 files changed

+262
-75
lines changed

6 files changed

+262
-75
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+
<!-- FIXME(fmease): Fill in this section once the semantics have been decided upon. -->
95+
96+
### `#[repr(transparent)]`
97+
98+
<!-- FIXME(fmease): Extract most parts into the section above. -->
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: 114 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -709,17 +709,15 @@ impl Item {
709709
Some(tcx.visibility(def_id))
710710
}
711711

712-
pub(crate) fn attributes(
712+
pub(crate) fn attributes<'tcx>(
713713
&self,
714-
tcx: TyCtxt<'_>,
714+
tcx: TyCtxt<'tcx>,
715715
cache: &Cache,
716716
keep_as_is: bool,
717717
) -> Vec<String> {
718718
const ALLOWED_ATTRIBUTES: &[Symbol] =
719719
&[sym::export_name, sym::link_section, sym::no_mangle, sym::non_exhaustive];
720720

721-
use rustc_abi::IntegerType;
722-
723721
let mut attrs: Vec<String> = self
724722
.attrs
725723
.other_attrs
@@ -739,67 +737,122 @@ impl Item {
739737
}
740738
})
741739
.collect();
742-
if !keep_as_is
743-
&& let Some(def_id) = self.def_id()
744-
&& let ItemType::Struct | ItemType::Enum | ItemType::Union = self.type_()
745-
{
746-
let adt = tcx.adt_def(def_id);
747-
let repr = adt.repr();
748-
let mut out = Vec::new();
749-
if repr.c() {
750-
out.push("C");
751-
}
752-
if repr.transparent() {
753-
// Render `repr(transparent)` iff the non-1-ZST field is public or at least one
754-
// field is public in case all fields are 1-ZST fields.
755-
let render_transparent = cache.document_private
756-
|| adt
757-
.all_fields()
758-
.find(|field| {
759-
let ty =
760-
field.ty(tcx, ty::GenericArgs::identity_for_item(tcx, field.did));
761-
tcx.layout_of(tcx.param_env(field.did).and(ty))
762-
.is_ok_and(|layout| !layout.is_1zst())
763-
})
764-
.map_or_else(
765-
|| adt.all_fields().any(|field| field.vis.is_public()),
766-
|field| field.vis.is_public(),
767-
);
768740

769-
if render_transparent {
770-
out.push("transparent");
771-
}
772-
}
773-
if repr.simd() {
774-
out.push("simd");
775-
}
776-
let pack_s;
777-
if let Some(pack) = repr.pack {
778-
pack_s = format!("packed({})", pack.bytes());
779-
out.push(&pack_s);
780-
}
781-
let align_s;
782-
if let Some(align) = repr.align {
783-
align_s = format!("align({})", align.bytes());
784-
out.push(&align_s);
785-
}
786-
let int_s;
787-
if let Some(int) = repr.int {
788-
int_s = match int {
789-
IntegerType::Pointer(is_signed) => {
790-
format!("{}size", if is_signed { 'i' } else { 'u' })
741+
if !keep_as_is && let Some(repr) = self.repr(tcx, cache) {
742+
attrs.push(repr);
743+
}
744+
745+
attrs
746+
}
747+
748+
/// Compute the *public* `#[repr]` of this item.
749+
///
750+
/// Read more about it here:
751+
/// https://doc.rust-lang.org/nightly/rustdoc/advanced-features.html#repr-documenting-the-representation-of-a-type
752+
fn repr<'tcx>(&self, tcx: TyCtxt<'tcx>, cache: &Cache) -> Option<String> {
753+
let def_id = self.def_id()?;
754+
let (ItemType::Struct | ItemType::Enum | ItemType::Union) = self.type_() else {
755+
return None;
756+
};
757+
758+
let adt = tcx.adt_def(def_id);
759+
let repr = adt.repr();
760+
761+
let is_visible = |def_id| cache.document_hidden || !tcx.is_doc_hidden(def_id);
762+
let is_field_public =
763+
|field: &'tcx ty::FieldDef| field.vis.is_public() && is_visible(field.did);
764+
765+
if repr.transparent() {
766+
// `repr(transparent)` is public iff the non-1-ZST field is public or
767+
// at least one field is public in case all fields are 1-ZST fields.
768+
let is_public = cache.document_private
769+
|| adt.variants().iter().all(|variant| {
770+
if !is_visible(variant.def_id) {
771+
return false;
791772
}
792-
IntegerType::Fixed(size, is_signed) => {
793-
format!("{}{}", if is_signed { 'i' } else { 'u' }, size.size().bytes() * 8)
773+
774+
let field = variant.fields.iter().find(|field| {
775+
let args = ty::GenericArgs::identity_for_item(tcx, field.did);
776+
let ty = field.ty(tcx, args);
777+
tcx.layout_of(tcx.param_env(field.did).and(ty))
778+
.is_ok_and(|layout| !layout.is_1zst())
779+
});
780+
781+
if let Some(field) = field {
782+
return is_field_public(field);
794783
}
795-
};
796-
out.push(&int_s);
797-
}
798-
if !out.is_empty() {
799-
attrs.push(format!("#[repr({})]", out.join(", ")));
800-
}
784+
785+
adt.variants().iter().all(|variant| {
786+
variant.fields.is_empty() || variant.fields.iter().any(is_field_public)
787+
})
788+
});
789+
790+
// Since `repr(transparent)` can't have any other reprs or
791+
// repr modifiers beside it, we can safely return early here.
792+
return is_public.then(|| "#[repr(transparent)]".into());
801793
}
802-
attrs
794+
795+
// Fast path which avoids looking through the variants and fields in
796+
// the common case of no `#[repr]` or in the case of `#[repr(Rust)]`.
797+
if !repr.c()
798+
&& !repr.simd()
799+
&& repr.int.is_none()
800+
&& repr.pack.is_none()
801+
&& repr.align.is_none()
802+
{
803+
return None;
804+
}
805+
806+
let is_public = cache.document_private
807+
|| if adt.is_enum() {
808+
// FIXME(fmease): Should we take the visibility of fields of variants into account?
809+
// FIXME(fmease): `any` or `all`?
810+
adt.variants().is_empty()
811+
|| adt.variants().iter().any(|variant| is_visible(variant.def_id))
812+
} else {
813+
// FIXME(fmease): `all` or `any`?
814+
adt.all_fields().all(is_field_public)
815+
};
816+
if !is_public {
817+
return None;
818+
}
819+
820+
let mut result = Vec::new();
821+
822+
if repr.c() {
823+
result.push("C");
824+
}
825+
if repr.simd() {
826+
result.push("simd");
827+
}
828+
let int_s;
829+
if let Some(int) = repr.int {
830+
int_s = match int {
831+
rustc_abi::IntegerType::Pointer(is_signed) => {
832+
format!("{}size", if is_signed { 'i' } else { 'u' })
833+
}
834+
rustc_abi::IntegerType::Fixed(size, is_signed) => {
835+
format!("{}{}", if is_signed { 'i' } else { 'u' }, size.size().bytes() * 8)
836+
}
837+
};
838+
result.push(&int_s);
839+
}
840+
let pack_s;
841+
if let Some(pack) = repr.pack {
842+
pack_s = format!("packed({})", pack.bytes());
843+
result.push(&pack_s);
844+
}
845+
let align_s;
846+
if let Some(align) = repr.align {
847+
align_s = format!("align({})", align.bytes());
848+
result.push(&align_s);
849+
}
850+
851+
if result.is_empty() {
852+
return None;
853+
}
854+
855+
Some(format!("#[repr({})]", result.join(", ")))
803856
}
804857

805858
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/inline_cross/auxiliary/repr.rs‎

Lines changed: 42 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,60 @@
11
#![feature(repr_simd)]
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,
69
}
7-
#[repr(simd, packed(2))]
10+
11+
#[repr(C)] // private
12+
pub struct ReprCPrivField {
13+
private: u8,
14+
pub public: i8,
15+
}
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,
25+
pub field: u8,
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)] // public
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

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