But maybe this would be better fixed through Rustdoc, by supporting topics / sections, and being able to “globally” set which standard topics you’re interested in e.g. I don’t do embedded so generally unsafe and explicit allocations I’m uninterested in, that stuff could be folded away / hidden in both the sidebar & main text.
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.
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.
Take generic associated types, for example: they’re a major new feature… but are conceptually just removing a potentially surprising limitation.
Or const generics: they really are a major new feature, but in general the code that can use them was a good deal more complex and inconsistent before.
You’d have a stronger argument about complexity creep on async—there was lots of demand for it, but it’s not clear that the design that is now frozen was in fact ideal.