I feel like rustdoc has been going through cycles of being useful, then growing beyond what the current design can handle well, and needing major changes again. It’s currently not good for discovery in std, because each type has far too many methods and each method has far too much text, with examples added to everything.
Wrt examples I feel like the examples are mostly obvious / uninteresting and thus have little value, but I’ve been in the field a while so that may well be an experience bias.
Alternatively some examples show the neat bits but not clearly because they’re artificial e.g. HashSet::insert demonstrates that it returns a bool via an assert_eq, you have to figure out how cool and useful that is (then gripe that other langages don’t give this info) separately.
Even uninteresting examples are absolutely crucial. I've taught Rust to many, many people, and one of the things that new users rave about is how the docs provide an executable example of every API, no matter how trivial. This especially matters for highly generic functions (which are very common in libstd), where the signature is extremely imposing but the usage is surprisingly simple.
Cannot agree hard enough. Nothing is more deeply infuriating than api documentation that just expects the reader to understand what the author means. The trivial examples of everything means I never feel like I’m guessing when it comes to rust’s standard library. I dearly love working with Python and it’s many included batteries but plenty of the most complex and by extension powerful parts of the Python standard library need the kind of “show me how to do everything this is capable of” type example documentation that Rust uses. Last notable one for me was the documentation about changing stopitetation to an explicit error, and how the behaviour differed pre and post change. It took me far to long to work out what changes I needed for some library code to be updated because the documentation demonstrates a few good examples but does not cover all permutations of the behaviour they changed. It’s a low level feature so obviously they can’t show everything it can be used to do but they should have at least tried to cover all the different fundamental behaviours of the code. This is something the community are doing better with now, in part because of the excellent example the rust community is setting for documentation of a programming language.
My guiding principle for the absolute minimum of API documentation is "If I read the documentation and want to use the thing I read, I should be able to copy/paste something from right there to get started with."
This isn't perfect (trait implementations...) but it's nice to see that it's been as helpful as I hoped it would be.
