Something you might not know about rust-doc is that you can document your implementation of traits. I have not seend this feature used a whole lot and it’s not commonly necessary so I was surprised when I tried it and it actually worked.

One example of where you might want to use this is if you implement the AsRef trait on something that has multiple fields that would make sense to be the returned shared reference.

For example:

pub struct DataHolder {
  pub a: Vec<u8>,
  pub b: Vec<u8>,
}

The trait implementation could include documentation on which of the fields will be referenced by the trait.

/// Gets a reference to [`field@DataHolder::a`].
impl AsRef<[u8]> for DataHolder {
  fn as_ref(&self) -> &[u8] {
    self.a.as_ref()
  }
}

This will produce the following documentation in rustdoc.

Trait documentation for data holder indicates that it creates a reference to the a field