Generated doc pages for types should include more info about the type's relationships #44024
Labels
C-feature-request
Category: A feature request, i.e: not implemented / a PR.
T-rustdoc
Relevant to the rustdoc team, which will review and decide on the PR/issue.
It would be useful if the generated doc page for each type had an expandable section at the bottom that shows functions (incl. methods of other types) in the crate where the type appears in the function's argument types or return type to see possible uses of a type that aren't apparent from its methods and trait impls.
It could be divided into two sections, one for where the type appears as input (so you'd look at the section when you already know how to get an instance of the type), and one for where the type appears as output (for where you'd look if you want to get an instance of the type when it's constructed by another function).
Another useful thing would be to have another expandable section of other types that this type is a (public) constituent of.
Together these sections paint a fuller picture of the the role this type plays in the crate and its relationships to everything else in the crate.
(This approach could then also be extended to inter-crate references.)
Of course it's encouraged to include info about the type's relationship in the doc comments but many crates's docs don't do that enough. Making the type's relationships more obvious in the above way would complement the doc comments.
Example: This page for DeviceHandle would have a link to Context.html::open_device_with_vid_pid and Device::open() and the page for Device would have a link to the Iterator impl for Devices and the page for Devices would have a link to DeviceList::iter() and DeviceList would have a link to Context::devices()...
Another example: PortSettings would have a link to SerialPort::configure().
This would make it much easier to find out all the necessary info from reading the doc.
The text was updated successfully, but these errors were encountered: