Lokathor / bytemuck

A crate for mucking around with piles of bytes
https://docs.rs/bytemuck
Apache License 2.0
697 stars 77 forks source link

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

Closed ia0 closed 4 months ago

ia0 commented 4 months ago

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 commented 4 months ago

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.