Could RustDoc include an index of references to doc items?

1

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?

2

This is actually implemented on nightly already. I forget the exact syntax, but you can provide directories where the examples will be scraped from.

2 Likes
3

It's called scrape-examples (RFC #3123). I believe it is enabled by default on docs.rs (example).

2 Likes
4

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.