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

fmease · 2023-10-18T09:24:29Z

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

Fixes #66401.
Fixes #128364.
Fixes #137440.

Only display the representation #[repr(REPR)] (where REPR is not Rust or transparent) of a given type if none of its variants (incl. the synthetic variants of structs) are #[doc(hidden)] and 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.

--document-{private,hidden}-items works as expected in this context, too.

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

src/librustdoc/clean/types.rs

rustbot · 2023-10-18T10:24:18Z

Some changes occurred in GUI tests.

cc @GuillaumeGomez

GuillaumeGomez · 2023-10-18T11:50:53Z

src/librustdoc/clean/types.rs

+            || if adt.is_enum() {
+                // FIXME(fmease): Should we take the visibility of fields of variants into account?
+                // FIXME(fmease): `any` or `all`?
+                adt.variants().is_empty()


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

@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?

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.

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?

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

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.

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.

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.

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

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 · 2024-06-24T14:17:40Z

☔ 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 · 2024-07-30T09:11:20Z

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

fmease · 2024-07-30T09:17:08Z

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 · 2024-07-31T14:26:21Z

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

rust-rfcbot · 2025-09-15T15:34:50Z

🔔 This is now entering its final comment period, as per the review above. 🔔

Escape "special characters" (e.g., double quotes `"` and line breaks `\n`). Escape HTML. Lastly, add regression tests and clean up existing tests.

rustbot · 2025-09-25T09:51:26Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

rust-rfcbot · 2025-09-25T15:35:53Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

GuillaumeGomez · 2025-09-25T15:37:22Z

Time to merge, thanks everyone!

@bors r=rustdoc rollup

bors · 2025-09-25T15:37:26Z

📌 Commit 85c193a has been approved by rustdoc

It is now in the queue for this repository.

…pr-heuristic, r=rustdoc rustdoc: hide `#[repr]` if it isn't part of the public ABI > [!IMPORTANT] > Temporarily stacked on top of PR rust-lang#146527; only the last commit is relevant! Follow-up to rust-lang#115439. Unblocks rust-lang#116743, CC `@dtolnay.` Fixes rust-lang#66401. Fixes rust-lang#128364. Fixes rust-lang#137440. Only display the representation `#[repr(REPR)]` (where `REPR` is not `Rust` or `transparent`) of a given type if none of its variants (incl. the synthetic variants of structs) are `#[doc(hidden)]` and 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. `--document-{private,hidden}-items` works as expected in this context, too. Moreover, we now also factor in the presence of `#[doc(hidden)]` when checking whether to show `repr(transparent)` or not.

Rollup of 8 pull requests Successful merges: - #116882 (rustdoc: hide `#[repr]` if it isn't part of the public ABI) - #135771 ([rustdoc] Add support for associated items in "jump to def" feature) - #141032 (avoid violating `slice::from_raw_parts` safety contract in `Vec::extract_if`) - #142401 (Add proper name mangling for pattern types) - #146293 (feat: non-panicking `Vec::try_remove`) - #146859 (BTreeMap: Don't leak allocators when initializing nodes) - #146924 (Add doc for `NonZero*` const creation) - #146933 (Make `render_example_with_highlighting` return an `impl fmt::Display`) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #116882 - fmease:rustdoc-generalized-priv-repr-heuristic, r=rustdoc rustdoc: hide `#[repr]` if it isn't part of the public ABI > [!IMPORTANT] > Temporarily stacked on top of PR #146527; only the last commit is relevant! Follow-up to #115439. Unblocks #116743, CC ``@dtolnay.`` Fixes #66401. Fixes #128364. Fixes #137440. Only display the representation `#[repr(REPR)]` (where `REPR` is not `Rust` or `transparent`) of a given type if none of its variants (incl. the synthetic variants of structs) are `#[doc(hidden)]` and 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. `--document-{private,hidden}-items` works as expected in this context, too. Moreover, we now also factor in the presence of `#[doc(hidden)]` when checking whether to show `repr(transparent)` or not.

Rollup of 8 pull requests Successful merges: - rust-lang/rust#116882 (rustdoc: hide `#[repr]` if it isn't part of the public ABI) - rust-lang/rust#135771 ([rustdoc] Add support for associated items in "jump to def" feature) - rust-lang/rust#141032 (avoid violating `slice::from_raw_parts` safety contract in `Vec::extract_if`) - rust-lang/rust#142401 (Add proper name mangling for pattern types) - rust-lang/rust#146293 (feat: non-panicking `Vec::try_remove`) - rust-lang/rust#146859 (BTreeMap: Don't leak allocators when initializing nodes) - rust-lang/rust#146924 (Add doc for `NonZero*` const creation) - rust-lang/rust#146933 (Make `render_example_with_highlighting` return an `impl fmt::Display`) r? `@ghost` `@rustbot` modify labels: rollup

Library: Remove remaining private `#[repr]` workarounds With rust-lang#116882 finally merged, gating these `repr`s behind cfg `not(doc)` is no longer necessary to achieve a private repr. Follow up to rust-lang#128046 (that was enabled via rust-lang#115439). With that, rust-lang#116743 is now fully realized at long last. cc `@dtolnay`

Library: Remove remaining private `#[repr]` workarounds With rust-lang#116882 finally merged, gating these `repr`s behind cfg `not(doc)` is no longer necessary to achieve a private repr. Follow up to rust-lang#128046 (that was enabled via rust-lang#115439). With that, rust-lang#116743 is now fully realized at long last. cc ``@dtolnay``

Rollup merge of #147095 - fmease:libprivrepr, r=dtolnay Library: Remove remaining private `#[repr]` workarounds With #116882 finally merged, gating these `repr`s behind cfg `not(doc)` is no longer necessary to achieve a private repr. Follow up to #128046 (that was enabled via #115439). With that, #116743 is now fully realized at long last. cc ``@dtolnay``

rustbot assigned notriddle Oct 18, 2023

This comment was marked as outdated.

Sign in to view

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Oct 18, 2023

This comment was marked as resolved.

Sign in to view

fmease added relnotes Marks issues that should be documented in the release notes of the next release. needs-fcp This change is insta-stable, or significant enough to need a team FCP to proceed. labels Oct 18, 2023

This comment has been minimized.

Sign in to view

fmease commented Oct 18, 2023

View reviewed changes

src/librustdoc/clean/types.rs Outdated Show resolved Hide resolved

fmease force-pushed the rustdoc-generalized-priv-repr-heuristic branch from 1608e1c to 0461b26 Compare October 18, 2023 10:24

fmease force-pushed the rustdoc-generalized-priv-repr-heuristic branch from 0461b26 to 79bb50a Compare October 18, 2023 10:41

GuillaumeGomez reviewed Oct 18, 2023

View reviewed changes

fmease changed the title ~~rustdoc: hide #[repr(...)] if it isn't part of the public ABI~~ rustdoc: hide #[repr] if it isn't part of the public ABI Nov 6, 2023

Dylan-DPC mentioned this pull request Nov 15, 2023

Eliminate use of #[cfg_attr(not(doc), repr(...))] #116743

Closed

camelid reviewed Feb 12, 2024

View reviewed changes

fmease mentioned this pull request Jul 22, 2024

Fix some #[cfg_attr(not(doc), repr(..))] #128046

Merged

fmease mentioned this pull request Jul 29, 2024

Repr is incorrectly documented for structs with hidden field #128364

Closed

dtolnay reviewed Jul 29, 2024

View reviewed changes

fmease added rla-silenced Silences rust-log-analyzer postings to the PR it's added on. and removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Jul 29, 2024

fmease force-pushed the rustdoc-generalized-priv-repr-heuristic branch from 79bb50a to dc27ca1 Compare July 29, 2024 23:06

This comment was marked as resolved.

Sign in to view

fmease added S-waiting-on-fcp Status: PR is in FCP and is awaiting for FCP to complete. and removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Sep 25, 2025

fmease added 3 commits September 25, 2025 10:16

rustdoc: Slightly clean up attr rendering

88e7977

rustdoc: Fully escape link section and export name

d7d7725

Escape "special characters" (e.g., double quotes `"` and line breaks `\n`). Escape HTML. Lastly, add regression tests and clean up existing tests.

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

85c193a

fmease force-pushed the rustdoc-generalized-priv-repr-heuristic branch from 940fb08 to 85c193a Compare September 25, 2025 09:51

rustbot mentioned this pull request Sep 25, 2025

Tracking issue for release notes of #116882: rustdoc: hide #[repr] if it isn't part of the public ABI #147034

Open

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 25, 2025

This was referenced Sep 25, 2025

Rollup of 6 pull requests #147036

Closed

Rollup of 8 pull requests #147037

Merged

bors merged commit a39d513 into rust-lang:master Sep 25, 2025
10 checks passed

rustbot added this to the 1.92.0 milestone Sep 25, 2025

fmease deleted the rustdoc-generalized-priv-repr-heuristic branch September 26, 2025 02:18

fmease mentioned this pull request Sep 27, 2025

Library: Remove remaining private #[repr] workarounds #147095

Merged

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

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

Conversation

fmease commented Oct 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as resolved.

This comment has been minimized.

Uh oh!

rustbot commented Oct 18, 2023

Uh oh!

GuillaumeGomez Oct 18, 2023

Choose a reason for hiding this comment

Uh oh!

fmease Oct 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Oct 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Oct 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Oct 18, 2023

Choose a reason for hiding this comment

Uh oh!

dtolnay Oct 18, 2023

Choose a reason for hiding this comment

Uh oh!

fmease Oct 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Oct 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Oct 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Oct 22, 2023

Choose a reason for hiding this comment

Uh oh!

camelid left a comment

Choose a reason for hiding this comment

Uh oh!

bors commented Jun 24, 2024

Uh oh!

dtolnay left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez commented Jul 30, 2024

Uh oh!

fmease commented Jul 30, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmease commented Jul 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

rust-rfcbot commented Sep 15, 2025

Uh oh!

rustbot commented Sep 25, 2025

Uh oh!

rust-rfcbot commented Sep 25, 2025

Uh oh!

GuillaumeGomez commented Sep 25, 2025

Uh oh!

bors commented Sep 25, 2025

Uh oh!

Uh oh!

Uh oh!

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

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

fmease commented Oct 18, 2023 •

edited

Loading

fmease Oct 18, 2023 •

edited

Loading

RalfJung Oct 18, 2023 •

edited

Loading

fmease Oct 18, 2023 •

edited

Loading

fmease Oct 19, 2023 •

edited

Loading

fmease Oct 19, 2023 •

edited

Loading

RalfJung Oct 19, 2023 •

edited

Loading

dtolnay left a comment •

edited

Loading

fmease commented Jul 30, 2024 •

edited

Loading

fmease commented Jul 31, 2024 •

edited

Loading