The 1574-more-api-documentation-conventions - The Rust RFC Book mostly focuses on documenting functions. Modules and traits don't get the same attention.
For example, for traits:
Erroris a trait representing the basic expectations for error values, i.e., values of type
Readtrait allows for reading bytes from a source.
A trait for converting a value to a
The addition operator
The first two are consistent with eachother, but it's redundant. The 3rd starts with "A trait", which is still a bit redundant. The 4th goes straight for "The addition operator". None of these seem like particularly good examples of how to write trait docs. The traits in std::convert, aside from AsRef/AsMut which are consistent with eachother, also seem like quite a ride: std::convert - Rust
Module docs also have similar consistency issues. Also, as a side-note, std::iter - Rust says:
Composable external iteration.
However, we've had Iterator in std::iter - Rust and friends for a while now, and those provide internal iteration. (oh yeah and
Iterator uses "An interface" as opposed to "A trait"!)
Would it be a bad idea to suggest defining some more conventions about trait and module documentation? Ppl do tend to use std doc guidelines as a starting point for writing their own crate docs, and at least to us it looks like that falls short for traits and modules.