rustdoc: hide #[repr] if it isn't part of the public ABI

[fmease]

Follow-up to #115439.
Unblocks #116743, CC @dtolnay.
Fixes #128364.

NB: Whenever I mention reprs below, I'm always excluding repr(transparent) and repr(Rust)!

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?

@ T-release, if this PR makes it into the same release as #115439, please merge their relnotes Marks issues that should be documented in the release notes of the next release. .

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 ↩

[rustbot]

r? @notriddle

(rustbot has picked a reviewer for you, use r? to override)

[rustbot]

Some changes occurred in src/librustdoc/clean/types.rs

cc @camelid

[rustbot]

Some changes occurred in GUI tests.

cc @GuillaumeGomez

[GuillaumeGomez]

I think I'd go for any in both cases.

[fmease]

@RalfJung, does it sound good to you as well to consider the repr public if there exists at least one struct field that is public (there might be private and hidden ones) (if we have a struct) or if there exists at least one non-hidden enum variant (if we have an enum)? (With the extra rule that empty structs and enums also render the repr public).

Or should all fields (current version of this PR) and enum variants be public for the repr to be public?

[RalfJung]

Usually for structs, if there is at least one private field then we say you can't rely on the struct staying how it is. For instance if your repr(transparent) relies on another type being a ZST and that type has at least one private field, we warn about that (and we eventually want to make that an error).

So I'd say the same should go for the repr. If any field is private, then the repr is (by default) private.

[fmease]

Thanks, that makes sense! What about enum variants? Can users still make certain assumptions about the repr of an enum if some but not all of its variants are private or hidden?

[RalfJung]

There's no such things as private enum variants (unfortunately).

[dtolnay]

on a struct with a doc(hidden) field, should the repr be shown?

Here is an example of what goes wrong if you show repr on a struct with doc(hidden) field.

#[repr(C)]
pub struct Struct {
    pub first: u8,
    #[doc(hidden)]
    pub second: u16,
    pub third: u8,
}

Rustdoc purports a repr(C) struct in which the first byte is first, the second byte is third, and some other fields follow. Given the Rust-like syntax in which rustdoc shows #[repr(C)], this feels misleading. For a struct that is actually this:

#[repr(C)]
pub struct Struct {
    pub first: u8,
    pub third: u8,
    // ... other fields ...
}

one would expect they can cast &Struct to &[u8; 2] and read first and third from it. If they do that in this case though, they get UB from looking at a padding byte.

I think this would be a useful bar to keep in mind as a minimum desirable property; rustdoc should not show a repr in such a way that misleads reader about reality. That does not necessarily need to mean hiding such reprs, though that might be the most expedient path forward. Alternatively rustdoc could be more discerning about placing the /*private field*/ comment in between the correct fields when there is a repr.

[fmease]

Hmm, do we already track this in a GitHub issue? With the introduction of core::mem::offset_of, it feels like we should up the priority of this issue. If I remember correctly, it'd need quite a bit of rewiring inside rustdoc to render /* private field */ in the correct order for repr(C) structs since those fields are stripped early at the moment.

[fmease]

RalfJung, re taking doc(hidden) on variants into account when computing the visibility of a repr, I've included that in the heuristic to hide the repr(u8) on core::ffi::c_void which has consists of two doc(hidden) enum variants.

[RalfJung]

Sounds to me then like we'd want to hide the repr as soon as there is any hidden field (just like we hide it as soon as there is any private field) -- both for struct and enum (and union).

[GuillaumeGomez]

Seems like there is more to discuss. I'll add it to the next rustdoc team meeting agenda.

[camelid]

In discussing this as part of the rustdoc meeting, I realized we probably need to account for whether #[non_exhaustive] has been applied to the struct/enum/etc. If it is, then the API isn't stable.

[bors]

☔ The latest upstream changes (presumably #126788) made this pull request unmergeable. Please resolve the merge conflicts.

[dtolnay]

This appears to be stalled on everyone agreeing on a comprehensive set of rules.

Since I ran into this again today in #128364, I'll try to suggest a way to make progress again: Is it possible we can agree to err on the side of not showing repr? Let's make rustdoc render repr in only the most incontrovertible circumstances: everything is pub, nothing is hidden, there is at least 1 field, there is at least one variant, etc. Feel free to add as many other restrictions here as it takes until everyone agrees that we've reached an overestimation of what the actual rules should be.

After that, we can incrementally agree to additional deliberate cases where repr should be made part of the documented API of a type. Each of these can be FCP'd with the team if needed.

The current state of erring on the side of rendering repr in too many cases that have not been agreed to is unfortunate.

[GuillaumeGomez]

I think it's good like this. Like @dtolnay mentioned, we can always add new rules later on. Should we start the FCP?

[fmease]

FCP

Not quite yet, I still need to update the approach, PR description and PR itself :) I'll do so in a moment. I've only rebased.

[fmease]

Thinking back to past discussions, one reason for being liberal in showing / conservative in hiding #[repr(...)] was the fact that there's currently no way to override this heuristic, i.e., to force rustdoc to show the repr. Ideas about a #[doc(repr(...))] were floating around.

Without it, users would need to declare this information in prose instead.

Thinking aloud, I guess it does make sense as a first step even if it's not the greatest (e.g., repr packed and C can be meaningful (as part of the public ABI) even if e.g. later fields are private/hidden as they don't necessarily influence the alignment and thus the offset of earlier public fields (for e.g., core::mem::offset_of)).

[bors]

☔ The latest upstream changes (presumably #129403) made this pull request unmergeable. Please resolve the merge conflicts.

[Dylan-DPC]

@fmease any updates on this? thanks