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

[fmease]

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

Only¹ display the representation² #[repr(…)] of a given type if none of its variants³ are #[doc(hidden)] and if all of its fields are public and not #[doc(hidden)] since it's likely not meant to be considered part of the public ABI otherwise.

Moreover, we now also factor in the presence of #[doc(hidden)] when checking whether to show repr(transparent).

Footnotes

1. We're respecting --document-{private,hidden}-items of course. ↩

2. This excludes the representations Rust (which we will never display explicitly) and transparent (for which we have custom rules, see rustdoc: hide #[repr(transparent)] if it isn't part of the public ABI #115439). ↩

3. 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.

[rustbot]

These commits modify tests/rustdoc-json.
rustdoc-json is a public (but unstable) interface.

Please ensure that if you've changed the output:

• It's intentional.
• The FORMAT_VERSION in src/librustdoc-json-types is bumped if necessary.

cc @aDotInTheVoid, @obi1kenobi

[fmease]

I'm very open to phrasing suggestions and ways to make this section and its subsection clearer! I feel like it could be much better!

[fmease]

Only¹ display the representation² #[repr(…)] of a given type if none of its variants³ are #[doc(hidden)] and if all of its fields are public and not #[doc(hidden)] since it's likely not meant to be considered part of the public ABI otherwise.

Moreover, we now also factor in the presence of #[doc(hidden)] when checking whether to show repr(transparent).

@rfcbot merge

Footnotes

1. We're respecting --document-{private,hidden}-items of course. ↩

2. This excludes the representations Rust (which we will never display explicitly) and transparent (for which we have custom rules, see rustdoc: hide #[repr(transparent)] if it isn't part of the public ABI #115439). ↩

3. 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. ↩

[rfcbot]

Team member @fmease has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @fmease
• @jsha
• @notriddle

Concerns:

• positive-bugs in cargo-semver-check resolved by rustdoc: hide #[repr] if it isn't part of the public ABI #116882 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[obi1kenobi]

I have significant concerns that this may cause unfixable false-positive bugs in cargo-semver-checks.

Doc hidden is not sufficient to indicate non-public-API status — attempting to define it in such a maximalist fashion results in an edge case where major breaking changes are allowed by Rust SemVer rules via a series of only non-major version updates.

Please don't merge this until I've had a chance to review more deeply. Otherwise cargo-semver-checks may be broken in an unfixable fashion.

[obi1kenobi]

In lieu of being able to list a concern (since I'm not on the review list), I'd like to ask someone on the list to add the concern on my behalf.

[GuillaumeGomez]

@rfcbot concern positive-bugs in cargo-semver-check

[fmease]

I've discussed this with @obi1kenobi in person and we came to the conclusion that we don't want to apply this heuristic / these rules for the JSON output at all. For historical context, we used to pass through the #[repr] unconditionally to the JSON output until very recently in PR #138018 which regressed that. I'll move the fix for the regression out of this PR.

For additional context, people currently abuse #[doc(hidden)] in the ecosystem to hide deprecated functions, hence Predrag's comment about doc(hidden) not being a 'reliable' way to denote exclusion from public API/ABI. However, we do want to consider #[doc(hidden)] for the HTML output in order to unblock #116743 because core/std uses doc(hidden) how it's intended to be used (e.g., c_void has two hidden variants and a repr that's meant to be private).

In a very far & hypothetical future where core/std use cargo-semver-checks themselves, there would now be a mismatch since CSC won't consider #[doc(hidden)] as marking things as excluded from the public API/ABI for pragmatic reasons (as mentioned above). However, that would affect every single other item in core/std that's marked hidden anyway already, so we would need to find a better solution anyway, therefore it shouldn't block this PR!

@rfcbot resolve positive-bugs

[GuillaumeGomez]

@rfcbot resolve positive-bugs in cargo-semver-check

[fmease]

Suggested change

	// `repr(transparent)` can only be applied to structs and one-variant enums.
	// `repr(transparent)` can only be applied to structs and single-variant enums.