Repository navigation
rustdoc: allow searching by trait bounds #84824
Description
https://docs.rs/hyper/0.14.7/hyper/client/conn/struct.Builder.html
Some libraries have trait bounds more complicated and more that one items, some of it could be automatically-derived or some could be specifically implemented for a certain structs/enums. Other libraries such as diesel also make use of trait bounds extensively.
pub fn handshake<T, B>(
&self,
io: T
) -> impl Future<Output = Result<(SendRequest<B>, Connection<T, B>)>> where
T: AsyncRead + AsyncWrite + Unpin + Send + 'static,
B: HttpBody + 'static,
B::Data: Send,
B::Error: Into<Box<dyn StdError + Send + Sync>>, If the user wants to find out which type can they used within the trait bound. According to the context above that they want to find out what can they use for T, they had to click on AsyncRead, capture all the implementations in mind and then go back and click on AsyncWrite and see which types appear again since trait bound is additive, it needs to satisfy all the traits.
If the user implemented a struct/enum that implemented all the specified trait bound then they know which is it, but if the user is using a third party library, chances are they will easily get lost or take some time to figure out what can T be without implementing it themselves. Without examples of the function, it would be require some time to go through and understand all the traits and their respective implementations.
Maybe we could have a way for user to know what could possibly be the types that they can use for T without going through the whole codebase? Behaving like goto implementation of language server, except now it can show what types satisfies all the specified trait bounds?
Of course the solution may not need to be perfect. I can think it may not work well with auto-traits since it could be hard to do that. Two solutions I can think of, we can have a implementations section within the search tab that shows all the types that satisfies the trait bounds specified, like AsyncRead + AsyncWrite (but not sure if we can also do it for Unpin or Send, maybe we couldn't cover lifetime at all). Another thing I can think of is that we can maybe provide some information when one clicks/hover on io or T then it will show the types that implement it, similar to the auto-traits section within the doc page.
Not sure if it is feasible, just an idea. Maybe we even had to have another search index if we can't reuse the existing one and not sure if it's worth it, or maybe we could make it lazily loaded only when they reached the tab. One issue I see is that types being shown may not be able to show standard library types and that may be an issue.
Activity
jsha commentedon Jun 3, 2021
I definitely see the utility of this, but I wonder if it might not be better solved by the documentation itself. For instance, right now the documentation for
handshakesays:Instead it could say:
The advantage of this approach is that it can work across crate boundaries, even when the crates are not built together. Right now, crates on docs.rs aren't aware of each other when built.
pickfire commentedon Jun 3, 2021
Yeah, what you said is good but in reality I have never seen any crates that have docs that do this. Documentation is good only if there are good documentation writers (rust have lots of good documentation but I see most low-level stuff documentation is bad), in any case we always have the trait bounds so giving the user the ability will always benefit the users compared to just documentation because we can't force how the documentation is written.
Document the typical value for an `io` param
jsha commentedon Jun 3, 2021
Here's an idea: we could look to see what types are used to satisfy T in a crate's tests, doctests, and internal code. Then we could offer a hover tip on
Tthat would say something like "example types that satisfy T: tokio::net::TcpStream, hyper::test::TestStream". That would solve the "crates aren't aware of each other at build time" problem. Which I realize now is not really accurate - a crate is aware of its own dependencies.jyn514 commentedon Jun 22, 2021
See rust-lang/rfcs#3123 for a more fleshed out idea around this.