Repr is incorrectly documented for structs with hidden field

[dtolnay]

#[repr(transparent)]
pub struct Public {
    pub field: i32,
}

#[repr(transparent)]
pub struct Private {
    field: i32,
}

#[repr(transparent)]
pub struct Hidden {
    #[doc(hidden)]
    pub field: i32,
}

Previous discussions of repr documentation:

• Hide #[repr(transparent)] where the field is non-public #90435
• rustdoc: hide #[repr(transparent)] if it isn't part of the public ABI #115439

I believe the intent was that repr(transparent) should only appear in rendered documentation if the field's type is a public API that the documentation reader gets to rely on.

This is the case for repro::Public, and not the case for repro::Private.

I believe repro::Hidden should be treated more like repro::Private for the purpose of documenting repr.

In the standard library, this currently impacts core::pin::Pin. https://doc.rust-lang.org/1.80.0/core/pin/struct.Pin.html

[fmease]

If I remember correctly my open PR #116882 from Oct '23 addresses this. It's still blocked on design decisions:

It's not entirely clear to me yet when exactly a repr is considered public or private.
What I've implemented: A repr is public iff

1. there exists a variant¹ that is not doc(hidden) or there are no variants at all and
2. for all struct fields (excl. enum variant struct fields) field, field is pub and not doc(hidden)

(while respecting --document-{private,hidden}-items of course).

However, it's not clear to me if the quantifiers above are correct, should they be swapped around or sth. else? Moreover, should we take the visibility of enum variant struct fields into account?

Footnotes

1. Here, variant refers to a (general) variant of an ADT which includes not only enum variants but also the single synthetic variant of structs and unions ↩