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

No documentation for the FooBits public type generated by derive(CheckedBitPattern) #235

Closed
ia0 opened this issue Apr 17, 2024 · 1 comment · Fixed by #236
Closed

No documentation for the FooBits public type generated by derive(CheckedBitPattern) #235

ia0 opened this issue Apr 17, 2024 · 1 comment · Fixed by #236

Comments

@ia0
Copy link
Contributor

ia0 commented Apr 17, 2024

Using derive(CheckedBitPattern) unconditionally triggers the missing_docs lint. This seems to be because the generated FooBits type is public and without documentation. For example, if a crate using bytemuck would have the following src/lib.rs:

//! foo.

#![warn(missing_docs)]

/// Foo.
#[derive(Copy, Clone, bytemuck::CheckedBitPattern)]
#[repr(C)]
pub struct Foo {
    /// x.
    x: u8,
}

There would be some FooBits public type generated as follow (according to cargo expand):

#[repr(C)]
pub struct FooBits {
    x: <u8 as ::bytemuck::CheckedBitPattern>::Bits,
}

This type does not have a documentation although Foo has one.

There are at least 3 options to solve this issue:

  1. Reuse the documentation of Foo for FooBits.
  2. Reuse the documentation of Foo for FooBits but slightly modify it to say that all bit patterns are valid.
  3. Generate a custom documentation for FooBits stating that it's a version of Foo with only valid bit patterns.
@Lokathor
Copy link
Owner

I'd love a PR for this.

I think option 3 is best, just add a docs line that the type is generated and doesn't need to be used by humans.

ia0 added a commit to ia0/bytemuck that referenced this issue Apr 17, 2024
Lokathor pushed a commit that referenced this issue Apr 17, 2024
zachs18 pushed a commit to zachs18/bytemuck that referenced this issue Jun 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants