rustdoc: fixed warnings and more improvements
Since the changes in wording can be more controversial, they've been done after the changeset that fixes the warnings.
The questions would be whether we want to add a check for a clean cargo doc
run and how. I am personally very found of rustdoc, I find it to be very useful (especially offline).