rustdoc-search: show type signature on type-driven SERP #124544

notriddle · 2024-04-30T00:49:55Z

This is a rewrite of #117112, based on feedback by @aDotInTheVoid.

Part of rust-lang/rust-project-goals#112

Preview

Preview page:

https://notriddle.com/rustdoc-html-demo-11/type-signature-v2/std/index.html?search=vec%3CU%3E%20-%3E%20%5BT%5D
https://notriddle.com/rustdoc-html-demo-11/type-signature-v2/std/index.html?search=option%3Ct%3E%20-%3E%20result%3Ct%3E
https://notriddle.com/rustdoc-html-demo-11/type-signature-v2/std/index.html?search=Vec%3CAllocator%3E%20-%3E%20Box%3C%5BT%5D%3E
https://notriddle.com/rustdoc-html-demo-11/type-signature-v2/std/index.html?search=Iterator%3CT%3E%2C%20(T->bool)%20-%3E%20(Extend%3CT%3E%2C%20Extend%3CT%3E)
https://notriddle.com/rustdoc-html-demo-11/type-signature-v2/std/index.html?search=new%20-%3E%20HashMap%3CK%2C%20V%2C%20S%3E (this is an old "bug report" from @Urgau — the results aren't any different, but the visible type signature and headline message makes it more obvious what's going on)

Screenshots:

Rationale

Since the point of this feature is to answer the question "why this a match," it's important that it communicates a few things:

How do I use this? This UI shows types as Rustdoc sees them, using Rustdoc's search syntax, rather than the syntax used by normal Rust. It's supposed to act as a built-in, context-sensitive tutorial, since you can type a name in, switch to the In Parameters tab, and see what you could've typed to get a particular result.
Which type parameters got matched to other type parameters? This information is found in a popover that you can open to see information about a search result. This makes the visible type signature a strict dump of the search index, providing reasonably clear separation of user input from output.
How does the search engine even work, anyway? It's important that this page accurately shows you what unboxing occurred and which mappings got followed. That's why parts of the highlighter are baked into the type unification function: it doesn't just show you where your atoms occur, but actually shows you which ones got matched. A highlighted "where clause" is also found in the About This Result popover.

This change doesn't touch deduplication. That logic needs some adjusting, but is separate enough from this problem to be done in a different PR.

How it works

A particular source of complexity in this PR is caused by storing the names of type parameters. Since this data is only needed after the results come up, loading them gets delayed until after the search is done, so that they can be loaded at the same time as the descriptions.

Future possibilities

This PR is based on #124148. This feature benefits from the type signature index itself being accurate, so we really kinda need full support for Rust's type grammar.

rustbot · 2024-04-30T00:50:04Z

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

GuillaumeGomez · 2024-04-30T09:09:06Z

I'll let @aDotInTheVoid confirms it looks good before reviewing the code.

rustbot · 2024-06-05T19:05:37Z

Some changes occurred in GUI tests.

cc @GuillaumeGomez

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha

bors · 2024-06-08T05:17:48Z

☔ The latest upstream changes (presumably #126144) made this pull request unmergeable. Please resolve the merge conflicts.

aDotInTheVoid · 2024-06-09T18:03:28Z

Having played around with this, I really like it. I think the searching side seems really solid and have some small nitpicks on the UI side. Feel free to disregard them, as I'm not great at this, and others on the rustdoc team have put alot more thaught into our UI than I have.

In rough order of importance:

The type signature should probably be in monospace. Seeing "Vec<u8> -> String" is much weirder to me than "Vec<u8> -> String"
I don't think the "About this result" infobox worth having in most (if not all cases), now that we use the source name for generics. It should defiantly be elided when it only had info like T is T
- Additionally, I'm not sure how nessesary it it to display the bounds here. Is saying K: HashEq helpfull here
  - Random aside: In the infobox they say K: HashEq, but have K: Hash + Eq
Really Small Thing: the (i) for notable traits changes color on highlight.
I don't love -> Vec<T> for a function that takes no arguments, but I don't have better ideas.

Thanks again for working on this, I'm really excited about having this!

GuillaumeGomez · 2024-06-09T21:42:31Z

src/librustdoc/html/static/css/rustdoc.css

@@ -2743,17 +2748,19 @@ Original by Dempfi (https://github.com/dempfi/ayu)
 	border-right: 1px solid #ffb44c;
 }

-:root[data-theme="ayu"] .search-results a:hover,
-:root[data-theme="ayu"] .search-results a:focus {
+:root[data-theme="ayu"] .search-results li:hover > a,


Having this special case for the ayu theme is really not great, we should try to either make a new variable or "fix" the ayu theme at some point (not for this PR).

src/librustdoc/html/static/js/main.js

src/librustdoc/html/static/js/search.js

GuillaumeGomez · 2024-06-09T21:56:09Z

Please also add a test for clicking on the i icon in the search results.

One final thought: I think, from what I understood of the code, that maybe it could be simplified to handle the notable trait part. I'll need to come back to this to ensure I didn't miss something obvious.

notriddle · 2024-06-11T19:10:13Z

Pushed changes to address nits:

switch color for ⓘ on hover
monospace type signature
omit bounds with no highlights and T is T name mappings
omit empty info popovers
fixed bounds formatting (added missing +s)
add more comments to code, minor cleanup

This commit is a response to feedback on the displayed type signatures results, by making type params looser and generics act stricter. Type params are loosened by allowing a single function type param to match multiple query params. In other words, the relationship is loosened to N:1 instead of the older 1:1 rule. This change also allows a type param to be unboxed in one spot and matched in another. Generics are tightened by making order significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected. Find the discussion on: * <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149> * <rust-lang#124544 (comment)>

GuillaumeGomez · 2024-09-25T00:43:21Z

cc @camelid

This commit is a response to feedback on the displayed type signatures results, by making type params looser and generics act stricter. Type params are loosened by allowing a single function type param to match multiple query params. In other words, the relationship is loosened to N:1 instead of the older 1:1 rule. This change also allows a type param to be unboxed in one spot and matched in another. Generics are tightened by making order significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected. Find the discussion on: * <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149> * <rust-lang#124544 (comment)>

bors · 2024-10-27T08:50:26Z

☔ The latest upstream changes (presumably #132213) made this pull request unmergeable. Please resolve the merge conflicts.

This reduces code size while still matching the common case for plain, concrete types.

This commit is a response to feedback on the displayed type signatures results, by making generics act stricter. Generics are tightened by making order significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected. Find the discussion on: * <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149> * <rust-lang#124544 (comment)> * <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search/near/476841363>

…GuillaumeGomez rustdoc-search: simplify rules for generics and type params **Heads up!**: This PR is a follow-up that depends on rust-lang#124544. It adds 12dc24f, a change to the filtering behavior, and 9900ea4, a minor ranking tweak. Part of rust-lang/rust-project-goals#112 This PR overturns rust-lang#109802 ## Preview * no results: [`Box<[A]> -> Vec<B>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CB%3E) * results: [`Box<[A]> -> Vec<A>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CA%3E) * [`T -> U`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=T%20-%3E%20U) * [`Cx -> TyCtxt`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3-compiler/rustdoc/index.html?search=Cx%20-%3E%20TyCtxt) ![image](https://github.com/user-attachments/assets/015ae28c-7469-4f7f-be03-157d28d7ec97) ## Description This commit is a response to feedback on the displayed type signatures results, by making generics act stricter. - Order within generics is significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected. - Generics are only "unboxed" if a type is explicitly opted into it. References and tuples are hardcoded to allow unboxing, and Box, Rc, Arc, Option, Result, and Future are opted in with an unstable attribute. Search result unboxing is the process that allows you to search for `i32 -> str` and get back a function with the type signature `&Future<i32> -> Box<str>`. - Instead of ranking by set overlap, it ranks by the number of items in the type signature. This makes it easier to find single type signatures like transmute. ## Find the discussion on * <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149> * <rust-lang#124544 (comment)> * <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search>

…Gomez rustdoc-search: simplify rules for generics and type params **Heads up!**: This PR is a follow-up that depends on #124544. It adds 12dc24f46007f82b93ed85614347a42d47580afa, a change to the filtering behavior, and 9900ea48b566656fb12b5fcbd0a1b20aaa96e5ca, a minor ranking tweak. Part of rust-lang/rust-project-goals#112 This PR overturns rust-lang/rust#109802 ## Preview * no results: [`Box<[A]> -> Vec<B>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CB%3E) * results: [`Box<[A]> -> Vec<A>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CA%3E) * [`T -> U`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=T%20-%3E%20U) * [`Cx -> TyCtxt`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3-compiler/rustdoc/index.html?search=Cx%20-%3E%20TyCtxt) ![image](https://github.com/user-attachments/assets/015ae28c-7469-4f7f-be03-157d28d7ec97) ## Description This commit is a response to feedback on the displayed type signatures results, by making generics act stricter. - Order within generics is significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected. - Generics are only "unboxed" if a type is explicitly opted into it. References and tuples are hardcoded to allow unboxing, and Box, Rc, Arc, Option, Result, and Future are opted in with an unstable attribute. Search result unboxing is the process that allows you to search for `i32 -> str` and get back a function with the type signature `&Future<i32> -> Box<str>`. - Instead of ranking by set overlap, it ranks by the number of items in the type signature. This makes it easier to find single type signatures like transmute. ## Find the discussion on * <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149> * <rust-lang/rust#124544 (comment)> * <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search>

rustbot assigned GuillaumeGomez Apr 30, 2024

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Apr 30, 2024

This comment has been minimized.

Sign in to view

notriddle force-pushed the notriddle/type-signature-v2 branch from 888ee4d to 681f0c2 Compare May 16, 2024 04:02

This comment has been minimized.

Sign in to view

notriddle marked this pull request as ready for review June 5, 2024 19:05

notriddle requested a review from aDotInTheVoid June 6, 2024 16:05

notriddle force-pushed the notriddle/type-signature-v2 branch from 0feb8de to ee3ee04 Compare June 8, 2024 14:57

This comment has been minimized.

Sign in to view

notriddle force-pushed the notriddle/type-signature-v2 branch from ee3ee04 to e350324 Compare June 8, 2024 15:45

This comment has been minimized.

Sign in to view

notriddle force-pushed the notriddle/type-signature-v2 branch from e350324 to f817d33 Compare June 8, 2024 16:28

This comment has been minimized.

Sign in to view

notriddle force-pushed the notriddle/type-signature-v2 branch from f817d33 to 801c978 Compare June 8, 2024 17:17

GuillaumeGomez reviewed Jun 9, 2024

View reviewed changes

src/librustdoc/html/static/js/main.js Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Jun 9, 2024

View reviewed changes

src/librustdoc/html/static/js/search.js Outdated Show resolved Hide resolved