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

Rustdoc: maybe don't display #[repr(C)] sometimes #66401

Open
CAD97 opened this issue Nov 14, 2019 · 1 comment
Open

Rustdoc: maybe don't display #[repr(C)] sometimes #66401

CAD97 opened this issue Nov 14, 2019 · 1 comment
Labels
A-attributes Area: Attributes (`#[…]`, `#![…]`) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@CAD97
Copy link
Contributor

CAD97 commented Nov 14, 2019

If a struct has some public fields and some non-public fields, // some fields omitted is displayed at the end of the declaration shown by rustdoc. Rustdoc also shows attributes on the declaration, such as #[repr(C)].

This is actively misleading for #[repr(C)] types. If a private type is before any public types, then the struct as displayed suggests that the public fields are at the prefix of the struct, and thus have defined offsets smaller than where they actually are.

Example:

#[repr(C)]
#[derive(Debug, Eq, PartialEq, Hash)]
pub struct ThinData<Head, SliceItem> {
    length: usize,
    pub head: Head,
    pub slice: [SliceItem],
}

image

There are two obvious potential solutions:

  • Put // some fields omitted in the correct place(s) among public fields for #[repr(C)] types, or
  • Don't display #[repr(C)] for types with some fields omitted.
@dtolnay
Copy link
Member

dtolnay commented Feb 5, 2023

Workaround: #[cfg_attr(not(doc), repr(C))] can be used to manually hide the attribute from documentation.

I agree rustdoc is incorrect by showing repr(C) on structs with a nonpublic field.

@dtolnay dtolnay added the A-attributes Area: Attributes (`#[…]`, `#![…]`) label Feb 5, 2023
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue May 16, 2023
Hide repr attribute from doc of types without guaranteed repr

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`:

- rust-lang#66401
- rust-lang#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 rust-lang#61969.

IMO that is even more confusing, even for standard library maintainers &mdash; see rust-lang#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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-attributes Area: Attributes (`#[…]`, `#![…]`) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

4 participants