3f68468bc6
rustdoc-search: add support for type parameters 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[^closure] 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) [^closure]: 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. |
||
|---|---|---|
| .. | ||
| src | ||
| anchor-navigable.goml | ||
| anchors.goml | ||
| basic-code.goml | ||
| check_info_sign_position.goml | ||
| check-code-blocks-margin.goml | ||
| check-stab-in-docblock.goml | ||
| code-blocks-overflow.goml | ||
| code-color.goml | ||
| code-sidebar-toggle.goml | ||
| code-tags.goml | ||
| codeblock-sub.goml | ||
| codeblock-tooltip.goml | ||
| cursor.goml | ||
| default-settings.goml | ||
| docblock-big-code-mobile.goml | ||
| docblock-code-block-line-number.goml | ||
| docblock-details.goml | ||
| docblock-table-overflow.goml | ||
| docblock-table.goml | ||
| duplicate-macro-reexport.goml | ||
| enum-variants.goml | ||
| escape-key.goml | ||
| extend-css.goml | ||
| fields.goml | ||
| font-weight.goml | ||
| go-to-collapsed-elem.goml | ||
| hash-item-expansion.goml | ||
| headers-color.goml | ||
| headings.goml | ||
| help-page.goml | ||
| highlight-colors.goml | ||
| huge-collection-of-constants.goml | ||
| huge-logo.goml | ||
| impl-default-expansion.goml | ||
| impl-doc.goml | ||
| implementors.goml | ||
| item-decl-colors.goml | ||
| item-info-alignment.goml | ||
| item-info-overflow.goml | ||
| item-info.goml | ||
| item-summary-table.goml | ||
| javascript-disabled.goml | ||
| jump-to-def-background.goml | ||
| label-next-to-symbol.goml | ||
| links-color.goml | ||
| list_code_block.goml | ||
| method-margins.goml | ||
| mobile.goml | ||
| module-items-font.goml | ||
| no-docblock.goml | ||
| notable-trait.goml | ||
| overflow-tooltip-information.goml | ||
| pocket-menu.goml | ||
| README.md | ||
| run-on-hover.goml | ||
| rust-logo.goml | ||
| scrape-examples-button-focus.goml | ||
| scrape-examples-color.goml | ||
| scrape-examples-fonts.goml | ||
| scrape-examples-layout.goml | ||
| scrape-examples-toggle.goml | ||
| search-corrections.goml | ||
| search-error.goml | ||
| search-filter.goml | ||
| search-form-elements.goml | ||
| search-input-mobile.goml | ||
| search-keyboard.goml | ||
| search-no-result.goml | ||
| search-reexport.goml | ||
| search-result-color.goml | ||
| search-result-description.goml | ||
| search-result-display.goml | ||
| search-result-go-to-first.goml | ||
| search-result-keyword.goml | ||
| search-tab-change-title-fn-sig.goml | ||
| search-tab.goml | ||
| setting-auto-hide-content-large-items.goml | ||
| setting-auto-hide-item-methods-docs.goml | ||
| setting-auto-hide-trait-implementations.goml | ||
| setting-go-to-only-result.goml | ||
| settings.goml | ||
| shortcuts.goml | ||
| sidebar-links-color.goml | ||
| sidebar-macro-reexport.goml | ||
| sidebar-mobile-scroll.goml | ||
| sidebar-mobile.goml | ||
| sidebar-source-code-display.goml | ||
| sidebar-source-code.goml | ||
| sidebar.goml | ||
| source-anchor-scroll.goml | ||
| source-code-page-code-scroll.goml | ||
| source-code-page.goml | ||
| src-font-size.goml | ||
| stab-badge.goml | ||
| struct-fields.goml | ||
| target.goml | ||
| theme-change.goml | ||
| theme-defaults.goml | ||
| theme-in-history.goml | ||
| toggle-click-deadspace.goml | ||
| toggle-docs-mobile.goml | ||
| toggle-docs.goml | ||
| toggle-implementors.goml | ||
| toggled-open-implementations.goml | ||
| trait-sidebar-item-order.goml | ||
| type-declation-overflow.goml | ||
| unsafe-fn.goml | ||
| warning-block.goml | ||
| where-whitespace.goml | ||
The tests present here are used to test the generated HTML from rustdoc. The goal is to prevent unsound/unexpected GUI changes.
This is using the browser-ui-test framework to do so. It works as follows:
It wraps puppeteer to send commands to a web browser in order to navigate and test what's being currently displayed in the web page.
You can find more information and its documentation in its repository.
If you need to have more information on the tests run, you can use --test-args:
$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --debug
If you don't want to run in headless mode (helpful to debug sometimes), you can use
--no-headless:
$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --no-headless
To see the supported options, use --help.
Important to be noted: if the chromium instance crashes when you run it, you might need to
use --no-sandbox to make it work:
$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --no-sandbox