I think it would be a lot easier to use RustDoc to analyze a crate if each doc item displayed a list of examples of its use. I might expect such a list to be hidden by default but clearly indicated and expandable, or appended to the very end of the doc page. A reference to an item should include the source crate / module path and 1-3 lines of context.
When considering this idea, a question arises: Where do you search to find references? I suspect that even a search that only included the current crate would significantly improve the "legibility" of many Rust crates. Notably this still allows the docs to be generated completely offline.
potential future enhancements
- Generating a static list by searching over an entire workspace at doc generation time.
- A dynamic rustdoc server that searches a whole registry.
I vaguely recall a conversation on a similar topic, but I was unable to find it. Has this been discussed elsewhere? Do you think a local-focused 'back-of-the-book' index would be useful enough to include it as a part of most doc items?