about summary refs log tree commit diff
path: root/src/librustdoc/html
AgeCommit message (Collapse)AuthorLines
2024-03-14Refactor visibility_print_with_space to directly take an itemManish Goregaokar-44/+23
2024-03-14print ghostsManish Goregaokar-0/+6
2024-03-14Rollup merge of #119676 - notriddle:notriddle/rustdoc-search-hof, ↵Matthias Krüger-115/+229
r=GuillaumeGomez rustdoc-search: search types by higher-order functions This feature extends rustdoc with syntax and search index information for searching function pointers and closures (Higher-Order Functions, or HOF). Part of https://github.com/rust-lang/rust/issues/60485 This PR adds two syntaxes: a high-level one for finding any kind of HOF, and a direct implementation of the parenthesized path syntax that Rust itself uses. ## Preview pages | Query | Results | |-------|---------| | [`option<T>, (fnonce (T) -> bool) -> option<T>`][optionfilter] | `Option::filter` | | [`option<T>, (T -> bool) -> option<T>`][optionfilter2] | `Option::filter` | Updated chapter of the book: https://notriddle.com/rustdoc-html-demo-9/search-hof/rustdoc/read-documentation/search.html [optionfilter]: https://notriddle.com/rustdoc-html-demo-9/search-hof/std/vec/struct.Vec.html?search=option<T>%2C+(fnonce+(T)+->+bool)+->+option<T>&filter-crate=std [optionfilter2]: https://notriddle.com/rustdoc-html-demo-9/search-hof/std/vec/struct.Vec.html?search=option<T>%2C+(T+->+bool)+->+option<T>&filter-crate=std ## Motivation When type-based search was first landed, it was directly [described as incomplete][a comment]. [a comment]: https://github.com/rust-lang/rust/pull/23289#issuecomment-79437386 Filling out the missing functionality is going to mean adding support for more of Rust's [type expression] syntax, such as references, raw pointers, function pointers, and closures. This PR adds function pointers and closures. [type expression]: https://doc.rust-lang.org/reference/types.html#type-expressions There's been demand for something "like Hoogle, but for Rust" expressed a few times [1](https://www.reddit.com/r/rust/comments/y8sbid/is_there_a_website_like_haskells_hoogle_for_rust/) [2](https://users.rust-lang.org/t/rust-equivalent-of-haskells-hoogle/102280) [3](https://internals.rust-lang.org/t/std-library-inclusion-policy/6852/2) [4](https://discord.com/channels/442252698964721669/448238009733742612/1109502307495858216). Some of them just don't realize what functionality already exists ([`Duration -> u64`](https://doc.rust-lang.org/nightly/std/?search=duration%20-%3E%20u64) already works), but a lot of them specifically want to search for higher-order functions like option combinators. ## Guide-level explanation (from the Rustdoc book) To search for a function that accepts a function as a parameter, like `Iterator::all`, wrap the nested signature in parenthesis, as in [`Iterator<T>, (T -> bool) -> bool`][iterator-all]. You can also search for a specific closure trait, such as `Iterator<T>, (FnMut(T) -> bool) -> bool`, but you need to know which one you want. [iterator-all]: https://notriddle.com/rustdoc-html-demo-9/search-hof/std/vec/struct.Vec.html?search=Iterator<T>%2C+(T+->+bool)+->+bool&filter-crate=std ## Reference-level description (also from the Rustdoc book) ### Primitives with Special Syntax <table> <thead> <tr> <th>Shorthand</th> <th>Explicit names</th> </tr> </thead> <tbody> <tr><td colspan="2">Before this PR</td></tr> <tr> <td><code>[]</code></td> <td><code>primitive:slice</code> and/or <code>primitive:array</code></td> </tr> <tr> <td><code>[T]</code></td> <td><code>primitive:slice&lt;T&gt;</code> and/or <code>primitive:array&lt;T&gt;</code></td> </tr> <tr> <td><code>!</code></td> <td><code>primitive:never</code></td> </tr> <tr> <td><code>()</code></td> <td><code>primitive:unit</code> and/or <code>primitive:tuple</code></td> </tr> <tr> <td><code>(T)</code></td> <td><code>T</code></td> </tr> <tr> <td><code>(T,)</code></td> <td><code>primitive:tuple&lt;T&gt;</code></td> </tr> <tr><td colspan="2">After this PR</td></tr> <tr> <td><code>(T, U -> V, W)</code></td> <td><code>fn(T, U) -> (V, W)</code>, Fn, FnMut, and FnOnce</td> </tr> </tbody> </table> The `->` operator has lower precedence than comma. If it's not wrapped in brackets, it delimits the return value for the function being searched for. To search for functions that take functions as parameters, use parenthesis. ### Search query grammar ```ebnf ident = *(ALPHA / DIGIT / "_") path = ident *(DOUBLE-COLON ident) [BANG] slice-like = OPEN-SQUARE-BRACKET [ nonempty-arg-list ] CLOSE-SQUARE-BRACKET tuple-like = OPEN-PAREN [ nonempty-arg-list ] CLOSE-PAREN arg = [type-filter *WS COLON *WS] (path [generics] / slice-like / tuple-like) type-sep = COMMA/WS *(COMMA/WS) nonempty-arg-list = *(type-sep) arg *(type-sep arg) *(type-sep) [ return-args ] generic-arg-list = *(type-sep) arg [ EQUAL arg ] *(type-sep arg [ EQUAL arg ]) *(type-sep) normal-generics = OPEN-ANGLE-BRACKET [ generic-arg-list ] *(type-sep) CLOSE-ANGLE-BRACKET fn-like-generics = OPEN-PAREN [ nonempty-arg-list ] CLOSE-PAREN [ RETURN-ARROW arg ] generics = normal-generics / fn-like-generics return-args = RETURN-ARROW *(type-sep) nonempty-arg-list exact-search = [type-filter *WS COLON] [ RETURN-ARROW ] *WS QUOTE ident QUOTE [ generics ] type-search = [ nonempty-arg-list ] query = *WS (exact-search / type-search) *WS ; unchanged parts of the grammar, like the full list of type filters, are omitted ``` ## Future direction ### The remaining type expression grammar As described in https://github.com/rust-lang/rust/pull/118194, this is another step in the type expression grammar: BareFunction, and the function-like mode of TypePath, are now supported. * RawPointerType and ReferenceType actually are a priority. * ImplTraitType and TraitObjectType (and ImplTraitTypeOneBound and TraitObjectTypeOneBound) aren't as much of a priority, since they desugar pretty easily. ### Search subtyping and traits This is the other major factor that makes it less useful than it should be. * `iterator<result<t>> -> result<t>` doesn't find `Result::from_iter`. You have to search [`intoiterator<result<t>> -> result<t>`](https://notriddle.com/rustdoc-html-demo-9/search-hof/std/vec/struct.Vec.html?search=intoiterator%3Cresult%3Ct%3E%3E%20-%3E%20result%3Ct%3E&filter-crate=std). Nobody's going to search for IntoIterator unless they basically already know about it and don't need the search engine anyway. * Iterator combinators are usually structs that happen to implement Iterator, like `std::iter::Map`. To solve these cases, it needs to look at trait implementations, knowing that Iterator is a "subtype of" IntoIterator, and Map is a "subtype of" Iterator, so `iterator -> result` is a subtype of `intoiterator -> result` and `iterator<t>, (t -> u) -> iterator<u>` is a subtype of [`iterator<t>, (t -> u) -> map<t -> u>`](https://notriddle.com/rustdoc-html-demo-9/search-hof/std/vec/struct.Vec.html?search=iterator%3Ct%3E%2C%20(t%20-%3E%20u)%20-%3E%20map%3Ct%20-%3E%20u%3E&filter-crate=std).
2024-03-12rustdoc: do not preload fonts when browsing locallyElijah Riggs-0/+2
2024-03-11rustdoc-search: add search query syntax `Fn(T) -> U`Michael Howell-48/+65
This is implemented, in addition to the ML-style one, because Rust does it. If we don't, we'll never hear the end of it. This commit also refactors some duplicate parts of the parser into a dedicated function.
2024-03-11rustdoc: use `const` for the special type name idsMichael Howell-25/+11
Initialize them before the search index is loaded.
2024-03-11rustdoc: clean up search.js by removing empty sort caseMichael Howell-5/+0
It's going to be a no-op on the empty list anyway (we have plenty of test cases that return nothing) so why send extra code?
2024-03-11rustdoc-search: parse and search with ML-style HOFMichael Howell-45/+161
Option::map, for example, looks like this: option<t>, (t -> u) -> option<u> This syntax searches all of the HOFs in Rust: traits Fn, FnOnce, and FnMut, and bare fn primitives.
2024-03-09rustdoc-search: depth limit `T<U>` -> `U` unboxingMichael Howell-31/+108
Profiler output: https://notriddle.com/rustdoc-html-demo-9/search-unbox-limit/ This is a performance enhancement aimed at a problem I found while using type-driven search on the Rust compiler. It is caused by [`Interner`], a trait with 41 associated types, many of which recurse back to `Self` again. This caused search.js to struggle. It eventually terminates, after about 10 minutes of turning my PC into a space header, but it's doing `41!` unifications and that's too slow. [`Interner`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/trait.Interner.html
2024-03-05Rename `DiagnosticMessage` as `DiagMessage`.Nicholas Nethercote-4/+4
2024-03-01Correctly generate item info of trait itemsGuillaume Gomez-13/+14
2024-02-29Rollup merge of #121689 - GuillaumeGomez:rustdoc-highlighting-whitespace, ↵Matthias Krüger-1/+2
r=notriddle [rustdoc] Prevent inclusion of whitespace character after macro_rules ident Discovered this bug randomly when looking at: ![image](https://github.com/rust-lang/rust/assets/3050060/dca38047-9085-4377-bfac-f98890224be4) We were too eagerly trying to merge tokens that shouldn't be merged together (for example if you have a code comment followed by a code comment, we merge them in one attribute to reduce the DOM size). r? ``@notriddle``
2024-02-28Auto merge of #121489 - nnethercote:diag-renaming, r=davidtwcobors-2/+2
Diagnostic renaming Renaming various diagnostic types from `Diagnostic*` to `Diag*`. Part of https://github.com/rust-lang/compiler-team/issues/722. There are more to do but this is enough for one PR. r? `@davidtwco`
2024-02-28Add regression test for inclusion of whitespace characters in rustdoc ↵Guillaume Gomez-1/+1
highlighting
2024-02-28Rename `DiagnosticBuilder` as `Diag`.Nicholas Nethercote-2/+2
Much better! Note that this involves renaming (and updating the value of) `DIAGNOSTIC_BUILDER` in clippy.
2024-02-27Prevent inclusion of whitespace character after macro_rules identGuillaume Gomez-0/+1
2024-02-27Fix link generation for locate foreign macro in jump to definition featureGuillaume Gomez-1/+1
2024-02-26Rollup merge of #121590 - GuillaumeGomez:rustdoc-js-changed, r=notriddleGuillaume Gomez-3/+11
Correctly handle if rustdoc JS script hash changed It's something that annoyed me for quite some time: I have nightly docs open (for both std and compiler). And often, I don't look at the page for some days. Then when I come back to it, I make a search... except nothing happens. Took me a while to figure out that it was because the hash of one of the JS files we load for the search (either `search.js` or `search-index.js`) was updated in the meantime, preventing the search to be done. To go around it, I added to press `ENTER` to make the form submitted (which would reload the same page but with the correct hashes this time and the search being run). r? `@notriddle`
2024-02-25Auto merge of #120393 - Urgau:rfc3373-non-local-defs, r=WaffleLapkinbors-5/+0
Implement RFC 3373: Avoid non-local definitions in functions This PR implements [RFC 3373: Avoid non-local definitions in functions](https://github.com/rust-lang/rust/issues/120363).
2024-02-25Correctly handle if rustdoc JS script hash changedGuillaume Gomez-3/+11
2024-02-24Rustdoc: include crate name in links for local primitivesGurinder Singh-2/+7
It makes the link easier to use in cases in which the path of the page where it will be embedded is not known beforehand such as when we generate impls dynamically from `register_type_impls` method in `main.js` Earlier for local primitives we would generate a path that was relative to the current page depth passed in `cx.current` . e.g if the current page was `std::simd::prelude::Simd` the generated path would be `../../primitive.<prim>.html` After this change the path will first take you to the the wesite root and add the crate name. e.g. for `std::simd::prelude::Simd` the path now will be `../../../std/primitive.<prim>.html`
2024-02-18Rollup merge of #121160 - fmease:rustdoc-fix-n-refactor-html-rendering, ↵León Orell Valerian Liehr-281/+173
r=GuillaumeGomez rustdoc: fix and refactor HTML rendering a bit * refactoring: get rid of a bunch of manual `f.alternate()` branches * not sure why this wasn't done so already, is this perf-sensitive? * fix an ICE in debug builds of rustdoc * rustdoc used to crash on empty outlives-bounds: `where 'a:` * properly escape const generic defaults * actually print empty trait and outlives-bounds (doesn't work for cross-crate reexports yet, will fix that at some other point) since they can have semantic significance * outlives-bounds: forces lifetime params to be early-bound instead of late-bound which is technically speaking part of the public API * trait-bounds: can affect the well-formedness, consider * makeshift “const-evaluatable” bounds under `generic_const_exprs` * bounds to force wf-checking in light of #100041 (quite artificial I know, I couldn't figure out something better), see https://github.com/rust-lang/rust/pull/121160#discussion_r1491563816
2024-02-18Rollup merge of #120526 - GuillaumeGomez:mobile-long-crate-name, r=notriddleLeón Orell Valerian Liehr-7/+2
rustdoc: Correctly handle long crate names on mobile Fixes https://github.com/rust-lang/rust/issues/120471. It now renders like this: ![image](https://github.com/rust-lang/rust/assets/3050060/065b4b8b-ba55-4163-a928-8d7bf735c111) r? `@notriddle`
2024-02-17Fix non_local_definitions lint in rustdocUrgau-5/+0
2024-02-16rustdoc: fix and refactor HTML rendering a bitLeón Orell Valerian Liehr-281/+173
2024-02-15add extra indent spaces for rust-playground linkyukang-2/+5
2024-02-09Unify item relative path computation in one functionGuillaume Gomez-24/+2
2024-02-09Correctly generate path for non-local items in source code pagesGuillaume Gomez-52/+140
2024-02-07hir: Remove `fn opt_hir_id` and `fn opt_span`Vadim Petrochenkov-2/+2
2024-02-05Rollup merge of #120641 - klensy:copypaste-me, r=notriddleMatthias Krüger-10/+21
rustdoc: trait.impl, type.impl: sort impls to make it not depend on serialization order Can be tested by running `cargo doc` with different rust versions on some crate and comparing `doc` folders: files in `trait.impl` and `type.impl` will sometimes have different order of impls.
2024-02-04rustdoc: trait.impl, type.impl: sort impls to make it not depend on ↵klensy-10/+21
serialization order
2024-01-31rustdoc: Correctly handle long crate names on mobileGuillaume Gomez-7/+2
2024-01-30Rollup merge of #117906 - GuillaumeGomez:improve-crate-name-hover, ↵Guillaume Gomez-4/+2
r=fmease,notriddle Improve display of crate name when hovered Currently when we hover the crate name, the background is stuck to the version and to the logo (when there is one): ![Screenshot from 2023-11-14 11-42-39](https://github.com/rust-lang/rust/assets/3050060/717190cd-483d-45a1-a462-e9ba342d4376) ![Screenshot from 2023-11-14 11-43-19](https://github.com/rust-lang/rust/assets/3050060/23f8bc9b-1304-4f91-ae1e-96bc508e9da6) I find it very unpleasant so I reduced the padding size and increased the margin (left and top) to keep the same positioning but not making it stuck anymore: ![Screenshot from 2024-01-29 20-40-11](https://github.com/rust-lang/rust/assets/3050060/82cf266c-7f99-4a46-a62b-ebe2445f52be) ![Screenshot from 2024-01-29 20-48-01](https://github.com/rust-lang/rust/assets/3050060/e7097c10-6e09-4bdc-a37f-070b6dac671d) [online docs](https://rustdoc.crud.net/imperio/improve-crate-name-hover/std/index.html) r? `@notriddle`
2024-01-30Rollup merge of #120250 - chadnorvell:rustdoc-xss, r=notriddleGuillaume Gomez-1/+9
rustdoc: Prevent JS injection from localStorage It turns out that you can execute arbitrary JavaScript on the rustdocs settings page. Here's how: 1. Open `settings.html` on a rustdocs site. 2. Set "preferred light theme" to "dark" to initialize the corresponding localStorage value. 3. Plant a payload by executing this in your browser's dev console: ``Object.keys(localStorage).forEach(key=>localStorage.setItem(key,`javascript:alert()//*/javascript:javascript:"/*'/*\`/*--></noscript></title></textarea></style></template></noembed></script><html " onmouseover=/*&lt;svg/*/onload=alert()onload=alert()//><svg onload=alert()><svg onload=alert()>*/</style><script>alert()</script><style>`));`` 4. Refresh the page -- you should see an alert. This could be particularly dangerous if rustdocs are deployed on a domain hosting some other application. Malicious code could circumvent `same-origin` policies and do mischievous things with user data. This change ensures that only defined themes can actually be selected (arbitrary strings from localStorage will not be written to the document), and for good measure sanitizes the theme name.
2024-01-29Improve display of crate name when hoveredGuillaume Gomez-4/+2
2024-01-29rustdoc: Prevent JS injection from localStorageChad Norvell-1/+9
2024-01-24Bump `askama` versionclubby789-7/+7
2024-01-23Rename `TyCtxt::struct_span_lint_hir` as `TyCtxt::node_span_lint`.Nicholas Nethercote-2/+2
2024-01-22Rollup merge of #119746 - notriddle:notriddle/resize-close-modals, r=fmeaseMatthias Krüger-0/+1
rustdoc: hide modals when resizing the sidebar Follow-up for https://github.com/rust-lang/rust/pull/119477#discussion_r1439085011 CC `@lukas-code`
2024-01-19Rollup merge of #117662 - GuillaumeGomez:links-in-headings, r=notriddleMatthias Krüger-83/+139
[rustdoc] Allows links in headings Reopening of https://github.com/rust-lang/rust/pull/94360. # Explanations Rustdoc currently doesn't follow the markdown spec on headings: we don't allow links in them. So instead of having headings linking to themselves, this PR generates an anchor on the left side like this: ![image](https://github.com/rust-lang/rust/assets/3050060/a118a7e9-5ef8-4d07-914f-46defc3245c3) <details> <summary>previous version</summary> ![image](https://github.com/rust-lang/rust/assets/3050060/c34fa844-9cd4-47dc-bb51-b37f5f66afee) </details> Having the anchor always displayed allows for mobile devices users to be able to have a link to the anchor. The different color used for the anchor itself is the same as links so people notice when looking at it that they can click on it. You can test it [here](https://rustdoc.crud.net/imperio/links-in-headings/std/index.html). cc `@camelid` r? `@notriddle`
2024-01-10Shorten some error invocations.Nicholas Nethercote-2/+1
- `struct_foo` + `emit` -> `foo` - `create_foo` + `emit` -> `emit_foo` I have made recent commits in other PRs that have removed some of these shortcuts for combinations with few uses, e.g. `struct_span_err_with_code`. But for the remaining combinations that have high levels of use, we might as well use them wherever possible.
2024-01-09Rollup merge of #119756 - notriddle:notriddle/reuse-map, r=GuillaumeGomezGuillaume Gomez-20/+91
rustdoc-search: reuse individual types in function signatures Because `search.js` never mutates the function signature after loading it, they can be safely and easily reused across functions. This change doesn't change the format of the search index. It only changes `search.js`. Profiler output: https://notriddle.com/rustdoc-html-demo-9/fn-signature-opti2/index.html <table><tr><th>benchmark<th>before<th>after <tr><th>arti<td> ``` user: 002.228 s sys: 000.315 s wall: 001.663 s child_RSS_high: 315668 KiB group_mem_high: 285948 KiB ``` <td> ``` user: 001.805 s sys: 000.231 s wall: 001.398 s child_RSS_high: 235864 KiB group_mem_high: 203056 KiB ``` <tr><th>cortex-m<td> ``` user: 000.143 s sys: 000.035 s wall: 000.140 s child_RSS_high: 59168 KiB group_mem_high: 23000 KiB ``` <td> ``` user: 000.138 s sys: 000.031 s wall: 000.133 s child_RSS_high: 58944 KiB group_mem_high: 22220 KiB ``` <tr><th>sqlx<td> ``` user: 000.792 s sys: 000.115 s wall: 000.536 s child_RSS_high: 156716 KiB group_mem_high: 122948 KiB ``` <td> ``` user: 000.824 s sys: 000.084 s wall: 000.535 s child_RSS_high: 136668 KiB group_mem_high: 101792 KiB ``` <tr><th>stm32f4<td> ``` user: 006.665 s sys: 003.533 s wall: 008.624 s child_RSS_high: 1037660 KiB group_mem_high: 1022516 KiB ``` <td> ``` user: 005.997 s sys: 003.185 s wall: 007.987 s child_RSS_high: 832068 KiB group_mem_high: 810908 KiB ``` <tr><th>stm32f4xx-hal<td> ``` user: 000.317 s sys: 000.051 s wall: 000.203 s child_RSS_high: 77060 KiB group_mem_high: 41776 KiB ``` <td> ``` user: 000.287 s sys: 000.046 s wall: 000.180 s child_RSS_high: 75216 KiB group_mem_high: 39200 KiB ``` <tr><th>ripgrep<td> ``` user: 000.463 s sys: 000.063 s wall: 000.295 s child_RSS_high: 101288 KiB group_mem_high: 66364 KiB ``` <td> ``` user: 000.472 s sys: 000.036 s wall: 000.247 s child_RSS_high: 82708 KiB group_mem_high: 47056 KiB ``` </tr></table>
2024-01-08rustdoc-search: intern function search typesMichael Howell-17/+72
This takes advantage of more reuse opportunities. Along with the empty object commit, they bringing memory usage down about 20% over the original.
2024-01-08Rustdoc and Clippy stop misusing Key for Ty -> (adt) DefIdMichael Goulet-2/+1
2024-01-08rustdoc-search: reuse empty map/array in function signaturesMichael Howell-5/+21
Map is implemented as a pointer to a mutable object. Rustdoc never mutates function signatures after constructing them, but the JS engine doesn't know that. To save a bunch of memory, use a single immutable map for every decoded type object with no bindings or generics.
2024-01-08rustdoc: hide modals when resizing the sidebarMichael Howell-0/+1
Follow-up for https://github.com/rust-lang/rust/pull/119477#discussion_r1439085011
2024-01-06Rollup merge of #118194 - notriddle:notriddle/tuple-unit, r=GuillaumeGomezMatthias Krüger-29/+74
rustdoc: search for tuples and unit by type with `()` This feature extends rustdoc to support the syntax that most users will naturally attempt to use to search for tuples. Part of https://github.com/rust-lang/rust/issues/60485 Function signature searches already support tuples and unit. The explicit name `primitive:tuple` and `primitive:unit` can be used to match a tuple or unit, while `()` will match either one. It also follows the direction set by the actual language for parens as a group, so `(u8,)` will only match a tuple, while `(u8)` will match a plain, unwrapped byte—thanks to loose search semantics, it will also match the tuple. ## Preview * [`option<t>, option<u> -> (t, u)`](<https://notriddle.com/rustdoc-html-demo-5/tuple-unit/std/index.html?search=option%3Ct%3E%2C option%3Cu%3E -%3E (t%2C u)>) * [`[t] -> (t,)`](<https://notriddle.com/rustdoc-html-demo-5/tuple-unit/std/index.html?search=[t] -%3E (t%2C)>) * [`(ipaddr,) -> socketaddr`](<https://notriddle.com/rustdoc-html-demo-5/tuple-unit/std/index.html?search=(ipaddr%2C) -%3E socketaddr>) ## Motivation When type-based search was first landed, it was directly [described as incomplete][a comment]. [a comment]: https://github.com/rust-lang/rust/pull/23289#issuecomment-79437386 Filling out the missing functionality is going to mean adding support for more of Rust's [type expression] syntax, such as tuples (in this PR), references, raw pointers, function pointers, and closures. [type expression]: https://doc.rust-lang.org/reference/types.html#type-expressions There does seem to be demand for this sort of thing, such as [this Discord message](https://discord.com/channels/442252698964721669/443150878111694848/1042145740065099796) expressing regret at rustdoc not supporting tuples in search queries. ## Reference description (from the Rustdoc book) <table> <thead> <tr> <th>Shorthand</th> <th>Explicit names</th> </tr> </thead> <tbody> <tr><td colspan="2">Before this PR</td></tr> <tr> <td><code>[]</code></td> <td><code>primitive:slice</code> and/or <code>primitive:array</code></td> </tr> <tr> <td><code>[T]</code></td> <td><code>primitive:slice&lt;T&gt;</code> and/or <code>primitive:array&lt;T&gt;</code></td> </tr> <tr> <td><code>!</code></td> <td><code>primitive:never</code></td> </tr> <tr><td colspan="2">After this PR</td></tr> <tr> <td><code>()</code></td> <td><code>primitive:unit</code> and/or <code>primitive:tuple</code></td> </tr> <tr> <td><code>(T)</code></td> <td><code>T</code></td> </tr> <tr> <td><code>(T,)</code></td> <td><code>primitive:tuple&lt;T&gt;</code></td> </tr> </tbody> </table> A single type expression wrapped in parens is the same as that type expression, since parens act as the grouping operator. If they're empty, though, they will match both `unit` and `tuple`, and if there's more than one type (or a trailing or leading comma) it is the same as `primitive:tuple<...>`. However, since items can be left out of the query, `(T)` will still return results for types that match tuples, even though it also matches the type on its own. That is, `(u32)` matches `(u32,)` for the exact same reason that it also matches `Result<u32, Error>`. ## Future direction The [type expression grammar](https://doc.rust-lang.org/reference/types.html#type-expressions) from the Reference is given below: <pre><code>Syntax Type : TypeNoBounds | <a href="https://doc.rust-lang.org/reference/types/impl-trait.html">ImplTraitType</a> | <a href="https://doc.rust-lang.org/reference/types/trait-object.html">TraitObjectType</a> <br> TypeNoBounds : <a href="https://doc.rust-lang.org/reference/types.html#parenthesized-types">ParenthesizedType</a> | <a href="https://doc.rust-lang.org/reference/types/impl-trait.html">ImplTraitTypeOneBound</a> | <a href="https://doc.rust-lang.org/reference/types/trait-object.html">TraitObjectTypeOneBound</a> | <a href="https://doc.rust-lang.org/reference/paths.html#paths-in-types">TypePath</a> | <a href="https://doc.rust-lang.org/reference/types/tuple.html#tuple-types">TupleType</a> | <a href="https://doc.rust-lang.org/reference/types/never.html">NeverType</a> | <a href="https://doc.rust-lang.org/reference/types/pointer.html#raw-pointers-const-and-mut">RawPointerType</a> | <a href="https://doc.rust-lang.org/reference/types/pointer.html#shared-references-">ReferenceType</a> | <a href="https://doc.rust-lang.org/reference/types/array.html">ArrayType</a> | <a href="https://doc.rust-lang.org/reference/types/slice.html">SliceType</a> | <a href="https://doc.rust-lang.org/reference/types/inferred.html">InferredType</a> | <a href="https://doc.rust-lang.org/reference/paths.html#qualified-paths">QualifiedPathInType</a> | <a href="https://doc.rust-lang.org/reference/types/function-pointer.html">BareFunctionType</a> | <a href="https://doc.rust-lang.org/reference/macros.html#macro-invocation">MacroInvocation</a> </code></pre> ImplTraitType and TraitObjectType (and ImplTraitTypeOneBound and TraitObjectTypeOneBound) are not yet implemented. They would mostly desugar to `trait:`, similarly to how `!` desugars to `primitive:never`. ParenthesizedType and TuplePath are added in this PR. TypePath is already implemented (except const generics, which is not planned, and function-like trait syntax, which is planned as part of closure support). NeverType is already implemented. RawPointerType and ReferenceType require parsing and fixes to the search index to store this information, but otherwise their behavior seems simple enough. Just like tuples and slices, `&T` would be equivalent to `primitive:reference<T>`, `&mut T` would be equivalent to `primitive:reference<keyword:mut, T>`, `*T` would be equivalent to `primitive:pointer<T>`, `*mut T` would be equivalent to `primitive:pointer<keyword:mut, T>`, and `*const T` would be equivalent to `primitive:pointer<keyword:const, T>`. Lifetime generics support is not planned, because lifetime subtyping seems too complicated. ArrayType is subsumed by SliceType right now. Implementing const generics is not planned, because it seems like it would require a lot of implementation complexity for not much gain. InferredType isn't really covered right now. Its semantics in a search context are not obvious. QualifiedPathInType is not implemented, and it is not planned. I would need a use case to justify it, and act as a guide for what the exact semantics should be. BareFunctionType is not implemented. Along with function-like trait syntax, which is formally considered a TypePath, it's the biggest missing feature to be able to do structured searches over generic APIs like `Option`. MacroInvocation is not parsed (macro names are, but they don't mean the same thing here at all). Those are gone by the time Rustdoc sees the source code.
2024-01-05Rollup merge of #119468 - notriddle:notriddle/compression, r=GuillaumeGomezMichael Goulet-139/+250
rustdoc-search: tighter encoding for f index Depends on https://github.com/rust-lang/rust/pull/119457 Two optimizations for the function signature search: * Instead of using JSON arrays, like `[1,20]`, it uses VLQ hex with no commas, like `[aAd]`. * This also adds backrefs: if you have more than one function with exactly the same signature, it'll not only store it once, it'll *decode* it once, and store in the typeIdMap only once. Based partially on discussions on zulip: https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/search.20index.20size Performance ----------- https://notriddle.com/rustdoc-html-demo-8/compression-perf-v2/index.html ### memory/time profiler output (for more details, consult the above link) <table> <thead><tr><th>benchmark<th>before<th>after</tr></thead> <tbody> <tr><th>arti<td> ``` user: 002.789 s sys: 000.390 s wall: 002.096 s child_RSS_high: 440796 KiB group_mem_high: 414924 KiB ``` </td><td> ``` user: 002.295 s sys: 000.278 s wall: 001.738 s child_RSS_high: 314588 KiB group_mem_high: 285220 KiB ``` </td></tr><tr><th>cortex-m<td> ``` user: 000.127 s sys: 000.030 s wall: 000.134 s child_RSS_high: 60264 KiB group_mem_high: 23824 KiB ``` </td><td> ``` user: 000.136 s sys: 000.038 s wall: 000.137 s child_RSS_high: 59204 KiB group_mem_high: 22712 KiB ``` </td></tr><tr><th>sqlx<td> ``` user: 000.887 s sys: 000.118 s wall: 000.592 s child_RSS_high: 190408 KiB group_mem_high: 157804 KiB ``` </td><td> ``` user: 000.798 s sys: 000.101 s wall: 000.525 s child_RSS_high: 159292 KiB group_mem_high: 126292 KiB ``` </td></tr><tr><th>stm32f4<td> ``` user: 013.884 s sys: 005.399 s wall: 013.149 s child_RSS_high: 1942244 KiB group_mem_high: 1954916 KiB ``` </td><td> ``` user: 006.128 s sys: 003.297 s wall: 007.994 s child_RSS_high: 1038108 KiB group_mem_high: 1023900 KiB ``` </td></tr><tr><th>ripgrep<td> ``` user: 000.441 s sys: 000.063 s wall: 000.264 s child_RSS_high: 109180 KiB group_mem_high: 74272 KiB ``` </td><td> ``` user: 000.408 s sys: 000.044 s wall: 000.238 s child_RSS_high: 101488 KiB group_mem_high: 66000 KiB ``` </td></tr></tbody></table> Size change ----------- standard library without gzip: ```console $ du -bs search-index-old.js search-index-new.js 4976370 search-index-old.js 4404391 search-index-new.js ``` ((4976370-4404391)/4404391)*100% = 12.9% with gzip: ```console $ du -hs search-index-old.js.gz search-index-new.js.gz 520K search-index-old.js.gz 504K search-index-new.js.gz $ du -bs search-index-old.js.gz search-index-new.js.gz 522092 search-index-old.js.gz 507654 search-index-new.js.gz ``` ((522092-507654)/507654)*100% = 2.8% Benchmarks are similarly shrunk. Without gzip: ```console $ du -hs tmp/{arti,cortex-m,sqlx,stm32f4,ripgrep}/toolchain_{old,new}/doc/search-index.js 10555067 tmp/arti/toolchain_old/doc/search-index.js 8921236 tmp/arti/toolchain_new/doc/search-index.js 77018 tmp/cortex-m/toolchain_old/doc/search-index.js 66676 tmp/cortex-m/toolchain_new/doc/search-index.js 2876330 tmp/sqlx/toolchain_old/doc/search-index.js 2436812 tmp/sqlx/toolchain_new/doc/search-index.js 63632890 tmp/stm32f4/toolchain_old/doc/search-index.js 52337438 tmp/stm32f4/toolchain_new/doc/search-index.js 631150 tmp/ripgrep/toolchain_old/doc/search-index.js 541646 tmp/ripgrep/toolchain_new/doc/search-index.js ``` With gzip: ```console $ du -bs tmp/{arti,cortex-m,sqlx,stm32f4,ripgrep}/toolchain_{old,new}/doc/search-index.js.gz 1618852 tmp/arti/toolchain_old/doc/search-index.js.gz 1582007 tmp/arti/toolchain_new/doc/search-index.js.gz 16109 tmp/cortex-m/toolchain_old/doc/search-index.js.gz 15831 tmp/cortex-m/toolchain_new/doc/search-index.js.gz 422257 tmp/sqlx/toolchain_old/doc/search-index.js.gz 411507 tmp/sqlx/toolchain_new/doc/search-index.js.gz 4454761 tmp/stm32f4/toolchain_old/doc/search-index.js.gz 4334924 tmp/stm32f4/toolchain_new/doc/search-index.js.gz 98312 tmp/ripgrep/toolchain_old/doc/search-index.js.gz 96864 tmp/ripgrep/toolchain_new/doc/search-index.js.gz $ du -hs tmp/{arti,cortex-m,sqlx,stm32f4,ripgrep}/toolchain_{old,new}/doc/search-index.j s.gz 1.6M tmp/arti/toolchain_old/doc/search-index.js.gz 1.6M tmp/arti/toolchain_new/doc/search-index.js.gz 24K tmp/cortex-m/toolchain_old/doc/search-index.js.gz 24K tmp/cortex-m/toolchain_new/doc/search-index.js.gz 424K tmp/sqlx/toolchain_old/doc/search-index.js.gz 412K tmp/sqlx/toolchain_new/doc/search-index.js.gz 4.3M tmp/stm32f4/toolchain_old/doc/search-index.js.gz 4.2M tmp/stm32f4/toolchain_new/doc/search-index.js.gz 108K tmp/ripgrep/toolchain_old/doc/search-index.js.gz 104K tmp/ripgrep/toolchain_new/doc/search-index.js.gz ```
2024-01-05Add notes about the serialization formatMichael Howell-7/+26
2024-01-05Rollup merge of #119586 - GuillaumeGomez:jump-to-def-static-methods, r=notriddleMichael Goulet-20/+32
[rustdoc] Fix invalid handling for static method calls in jump to definition feature I realized when working on a clippy lint that static method calls on `Self` could not give me the method `Res`. For that, we need to use `typeck` and so that's what I did in here. It fixes the linking to static method calls. r? ````@notriddle````