Revisiting spotlight / "notable traits" in rustdoc

tools and infrastructure
4

This looks nice, but I would change the works. Instead of "an Iterator of &T", which doesn't work for all types, I would use something like "impl Iterator<Item = &'a T>", possibly using the same 'a and T as the impl block/fn generics that are used.

For example if we had:

impl<'a, T> Iterator for Iter<'a, T> {
    type Item = &'a T;
    // ...
}

impl<U> [U] {
    pub fn iter(&self) -> Iter<'_, U> { /* ... */ }
}

Then in the docs, on the right of the function signature, there would be written "impl Iterator<Item = &'_ U>".

Possible downsides:

  • This may create confusion with lifetimes, in particular elided lifetimes
  • If the type of Item (or other types present in the trait implementation) are pretty long this could easily get out of control.
  • How do you show multiple notable traits? Think for example of types that implement both Read and BufRead, or Iterator and FusedIterator

It would also be nice to have a way to restrict/select notable traits. For example in the docs of Iterator::by_ref I don't care that the returned reference may implement Read, I only care about Iterator.

1 Like