rustdoc-search: add support for type parameters

[notriddle]

r? @GuillaumeGomez

Preview

• https://notriddle.com/rustdoc-html-demo-4/advanced-search/rustdoc/read-documentation/search.html
• https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=option%3Coption%3CT%3E%3E%20-%3E%20option%3CT%3E
• https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=option%3CT%3E,%20E%20-%3E%20result%3CT,%20E%3E
• https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=-%3E%20option%3CT%3E

Description

When writing a type-driven search query in rustdoc, specifically one with more than one query element, non-existent types become generic parameters instead of auto-correcting (which is currently only done for single-element queries) or giving no result. You can also force a generic type parameter by writing generic:T (and can force it to not use a generic type parameter with something like struct:T or whatever, though if this happens it means the thing you're looking for doesn't exist and will give you no results).

There is no syntax provided for specifying type constraints for generic type parameters.

When you have a generic type parameter in a search query, it will only match up with generic type parameters in the actual function, not concrete types that match, not concrete types that implement a trait. It also strictly matches based on when they're the same or different, so option<T>, option<U> -> option<U> matches Option::and, but not Option::or. Similarly, option<T>, option<T> -> option<T> matches Option::or, but not Option::and.

Motivation

This feature is motivated by the many "combinitor"-type functions found in generic libraries, such as Option, Future, Iterator, and Entry. These highly-generic functions have names that are almost completely arbitrary, and a type signature that tells you what it actually does.

This PR is a major step towards¹ being able to easily search for generic functions by their type signature instead of by name. Some examples of combinators that can be found using this PR (try them out in the preview):

• option<option<T>> -> option<T> returns Option::flatten
• option<T> -> result<T> returns Option::ok_or
• option<result<T>> -> result<option<T>> returns Option::transpose
• entry<K, V>, FnOnce -> V returns Entry::or_insert_with (and or_insert_with_key, since there's no way to specify the generics on FnOnce)

Footnotes

1. For this feature to be as useful as it ought to be, you should be able to search for trait-associated types and closures. This PR does not implement either of these: they are Future possibilities.

   Trait-associated types would allow queries like option<T> -> iterator<item=T> to return Option::iter. We should also allow option<T> -> iterator<T> to match the associated type version.

   Closures would make a good way to query for things like Option::map. Closure support needs associated types to be represented in the search index, since FnOnce() -> i32 desugars to FnOnce<Output=i32, ()>, so associated trait types should be implemented first. Also, we'd want to expose an easy way to query closures without specifying which of the three traits you want. ↩

[rustbot]

Some changes occurred in GUI tests.

cc @GuillaumeGomez

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @Folyd, @jsha

Some changes occurred in src/librustdoc/clean/types.rs

cc @camelid

[GuillaumeGomez]

If I remember correctly, having exact match when more than one element is present in the search query is voluntary. Unless I misunderstood what this PR is about?

cc @jsha too

[notriddle]

If I remember correctly, having exact match when more than one element is present in the search query is voluntary.

I'm not sure what you mean by that. Is it about whether the names of types in a function signature-based search are exactly matched? Because, ever since #90630, having more than one element in a search query has implied that the items are matched exactly, and putting quotes around a query element has only been allowed if there's exactly one of them.

#110371 made that feature load-bearing, by assigning every type a numeric ID and mapping names to numbers before the type unification algorithm is actually run. I didn't benchmark it, because the primary motivation was actually UX rather than perf, but I suspect it made search.js use a little more memory and a lot less CPU time. It also means, if you write a query with more than one element in it, and one of them fails to match, you get no result. Try this preview against the current nightly build: https://doc.rust-lang.org/nightly/std/?search=vec%20-%3E%20uisze.

This PR further builds on that. Try the same query on my preview: https://notriddle.com/rustdoc-demo-html-3/advanced-search/std/index.html?search=vec%20-%3E%20uisze. Since uisze doesn't exist, it is implied to be a generic type parameter (it also detects the likely mistake and gives a warning, because the difference between vec -> t and vec -> uisze is a heuristic and not an actual rule).

[GuillaumeGomez]

Ok, thanks for the clarification, I misunderstood your explanations.

[GuillaumeGomez]

Mostly code improvement suggestions. Nice work!

[GuillaumeGomez]

Thanks!

@bors r+ rollup

[bors]

📌 Commit 3c5ada25f748837363ceacda813d1d2d5474c79e has been approved by GuillaumeGomez

It is now in the queue for this repository.

[notriddle]

@bors r-

@rfcbot fcp merge

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[GuillaumeGomez]

Thanks, it's a very nice improvement!

@bors r+

[bors]

📌 Commit 4cf06e8 has been approved by GuillaumeGomez

It is now in the queue for this repository.