Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generated doc pages for types should include more info about the type's relationships #44024

Open
Boscop opened this issue Aug 22, 2017 · 1 comment
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.

Comments

@Boscop
Copy link

Boscop commented Aug 22, 2017

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.

@Mark-Simulacrum Mark-Simulacrum added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. C-feature-request Category: A feature request, i.e: not implemented / a PR. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. labels Aug 22, 2017
@QuietMisdreavus
Copy link
Member

It's not a total fix, but #45055 should help this out by exposing this information to the search box.

@ehuss ehuss removed the T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. label Jan 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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.
Projects
None yet
Development

No branches or pull requests

4 participants