Earlier quoted context omitted.
That's not wrong. 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 grip…
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.
Re: Rust Survey 2021 Results
#101Cannot 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.