Repr is incorrectly documented for structs with hidden field

#[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:

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

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

there exists a variant¹ that is not doc(hidden) or there are no variants at all and

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?

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 ↩

Auto merge of #116882 - fmease:rustdoc-generalized-priv-repr-heuristi…

Rollup merge of rust-lang#116882 - fmease:rustdoc-generalized-priv-re…

Unrolled build for #116882

Rollup merge of #116882 - fmease:rustdoc-generalized-priv-repr-heuris…

Navigation Menu

Repository navigation

Repr is incorrectly documented for structs with hidden field #128364

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Repr is incorrectly documented for structs with hidden field #128364

Description

Activity

fmease commented on Jul 29, 2024

Footnotes

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions