Monomorphized docs

language design
1

I’d like to have a #[doc(monomorphized)] attribute for trait impls.

When writing code like so:

/// An API for interacting with raw data.
pub trait RawData {
  const ID: u8;
  fn read<R: Read>(reader: &mut R) -> io::Result<Self>;
  fn write<W: Write>(&self, writer: &mut W) -> io::Result<usize>;
}

// This is doc(hidden) because this shouldn't need to be `pub` at all but
// the compiler complains :<
// The type is expected to be Copy and Sized (and "Zeroable" which isn't a thing but I wish it was.)
#[doc(hidden)]
pub unsafe trait UnsafeRawData: Copy + Sized {
  const ID: u8;
}

// THIS IS THE IMPORTANT BIT
impl<T: UnsafeRawData> RawData for T {
  const ID: u8 = <T as UnsafeRawData>::ID;
  fn read<R: Read>(reader: &mut R) -> io::Result<T> {
    unsafe {
      let mut me: T = mem::zeroed();
      let size = mem::size_of<T>();
      let mut bytes = me as *mut T as *mut u8;
      /* something something, read_exact into bytes using slice::from_raw_parts_mut, .and(Ok(size)) the result */
    }
  }
  fn write<W: Write>(&self, writer: &mut W) -> io::Result<usize> {
    unsafe {
      /* similar to the above, but transmuting to writer instead */
    }
  }
}

The resulting docs look like:

## Implementors
impl<T> RawData for T where T: UnsafeRawData

It would be nice to be able to monomorphize trait impls, so it would instead look like:

## Implementors
impl RawData for MyRawData
impl RawData for VeryRawData
...

This would be done by applying #[doc(monomorphized)] to the trait impl.

(It would also be nice to support that trait impl with the trait being private, which may or may not be something for another feature/pre-RFC(?). Or maybe it should be part of this feature/pre-RFC(?) since I’m posting this on the language-design tag and not on the… whatever the tag for doctool changes is?)

2

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.