Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Hide repr attribute from doc of types without guaranteed repr #107680

Merged
merged 1 commit into from
May 16, 2023

Conversation

dtolnay
Copy link
Member

@dtolnay dtolnay commented Feb 5, 2023

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:

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
Copy link
Collaborator

rustbot commented Feb 5, 2023

r? @Mark-Simulacrum

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

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Feb 5, 2023
@rustbot
Copy link
Collaborator

rustbot commented Feb 5, 2023

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 Mark-Simulacrum added I-libs-api-nominated Nominated for discussion during a libs-api team meeting. I-libs-nominated Nominated for discussion during a libs team meeting. labels Feb 6, 2023
@Mark-Simulacrum
Copy link
Member

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
Copy link
Member

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.

@m-ou-se m-ou-se removed the I-libs-api-nominated Nominated for discussion during a libs-api team meeting. label Feb 7, 2023
@m-ou-se m-ou-se removed the I-libs-nominated Nominated for discussion during a libs team meeting. label Feb 22, 2023
@Amanieu
Copy link
Member

Amanieu commented Feb 22, 2023

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
Copy link
Member

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

@Mark-Simulacrum Mark-Simulacrum added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 25, 2023
@dtolnay
Copy link
Member Author

dtolnay commented Apr 23, 2023

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
Copy link
Contributor

bors commented May 4, 2023

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

@dtolnay
Copy link
Member Author

dtolnay commented May 16, 2023

@Amanieu
Copy link
Member

Amanieu commented May 16, 2023

@bors r+ rollup

@bors
Copy link
Contributor

bors commented May 16, 2023

📌 Commit e7963a6 has been approved by Amanieu

It is now in the queue for this repository.

@bors 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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels May 16, 2023
bors added a commit to rust-lang-ci/rust that referenced this pull request May 16, 2023
…iaskrgr

Rollup of 7 pull requests

Successful merges:

 - rust-lang#107680 (Hide repr attribute from doc of types without guaranteed repr)
 - rust-lang#111488 (Use error term in projection if missing associated item in new solver)
 - rust-lang#111533 (Handle error body in generator layout)
 - rust-lang#111573 (Erase `ReError` properly)
 - rust-lang#111592 (Change Vec examples to not assert exact capacity except where it is guaranteed)
 - rust-lang#111610 (fix(diagnostic): wrap parens for ref impl trait param)
 - rust-lang#111642 ([rustdoc] Only keep impl blocks from bodies)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 8d162fb into rust-lang:master May 16, 2023
@rustbot rustbot added this to the 1.71.0 milestone May 16, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants