Currently, std does a pretty bad job of documenting trait impls. Most of them aren't documented at all, sometimes you're lucky to find weird ones documented like std::collections::hash_map::RandomState - Rust. This one makes a bad example for adding a doctest tho.
It'd be cool if e.g. Default for u32 included a doctest tho, a simple
assert_eq!(u32::default(), 0u32);
It'd be extra-cool if various Iterator impls also included doctests. e.g. Range currently doctests the Range syntax and some other things, but its Iterator impl does not include any doctests anywhere. Does the Iterator for Range actually work? probably! It's probably being tested elsewhere anyway, but, arguably, it should also have a doctest to go with it. Also, Range and Iterator are an interesting combo because Range has an exact size among other things, so its doctests could also include that property.
However, all this raises an issue: currently we don't know of any RFC that attempts to define a convention/best practices for documenting trait impls. At least for the case of Iterator, and at least for impl Iterator for Range
, it'd make sense to have doctests on all the methods it overrides: next
, size_hint
, min
, max
, last
, nth
. But others might feel different about something like Default
- they might argue only the impl should be documented, or they might argue only the fn items should be documented. Anyway we figured we'd bring this all up so we can try to come up with something here.