Lokathor/bytemuck

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

ia0 opened this issue · 1 comments

ia0 commented

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.

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.