Hide repr attribute from doc of types without guaranteed repr

[dtolnay]

Rustdoc has an undesirable behavior of blindly copying repr into the documentation of structs and enums, even when there is no particular repr that the type guarantees to its users. This is a source of confusion for standard library users who assume the fact that a repr is documented means it must be something the standard library promises they can rely on (in transmutes, or FFI).

Some issues on the topic of rustdoc's incorrect handling of repr:

• Rustdoc: maybe don't display #[repr(C)] sometimes #66401
• Hide #[repr(transparent)] where the field is non-public #90435

In places, the standard library currently works around this confusing rustdoc behavior by just omitting repr(transparent) altogether even where it should be required if equivalent code were being written outside of the standard library. See #61969.

IMO that is even more confusing, even for standard library maintainers — see #105018 (comment). It's also not something that works for other reprs like C or u8 which cannot just be omitted even in standard library code.

This PR tries a different approach for some types that are being currently incorrectly documented with a repr.

Warning
This PR does not imply that every type that still has a repr attribute in its docs after this PR is now public for users to rely on. This PR only tries to reduce harm from this longstanding rustdoc issue.

[rustbot]

r? @Mark-Simulacrum

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

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[Mark-Simulacrum]

r=me, but I want to get some additional eyes from libs-api + libs (nominated) -- I think it's worth at least raising awareness for future additions of repr in std, so we can consider always employing this pattern.

[Mark-Simulacrum]

One other thought: we may want to explicitly document when the repr can be relied on with at least a code-comment (i.e., not doc comment), so that we can be more explicit about when it is public API and when not.

[Amanieu]

I think #66401 is the proper way of handling this: rustdoc should only show #[repr] when all fields are public, otherwise the layout of the struct is not public and should not be relied on.

I don't think we should pollute the standard library with these cfg_attr annotations, it's going to be a pain to maintain.

cc @GuillaumeGomez

[GuillaumeGomez]

I agree with @Amanieu. It might still need the approval of the rest of the team but I think it's a better approach.

[dtolnay]

It sounds like I prefer adding these few attributes so that the burden is on standard library maintainers until the rustdoc bug is fixed, while @Amanieu prefers not adding these attributes so the burden is on users until the rustdoc bug is fixed (and also on standard library maintainers in mediating situations where users have reached a faulty understanding of standard library guarantees due to misleading rustdoc rendered documentation, and also on standard library maintainers in the Path/PathBuf/OsStr case where the same rustdoc bug has been worked around in a worse way than this; see #105018 (review)).

[bors]

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

[dtolnay]

• Rebase to resolve conflict with Add cross-language LLVM CFI support to the Rust compiler #105452 in library/core/src/ffi/mod.rs
• and Sync portable-simd to 2023 May 10 #111475 in library/portable-simd/crates/core_simd/src/masks.rs

[Amanieu]

@bors r+ rollup

[bors]

📌 Commit e7963a6 has been approved by Amanieu

It is now in the queue for this repository.