Skip to content

Commit

Permalink
Auto merge of #111958 - notriddle:notriddle/type-search-slice-array, …
Browse files Browse the repository at this point in the history
…r=GuillaumeGomez

rustdoc: search for slices and arrays by type with `[]`

This feature extends rustdoc to support the syntax that most users will naturally attempt to use to search for slices and arrays. Part of #60485

Function signature searches already support arrays and slices. The explicit name `primitive:slice<u8>` and `primitive:array<u8>` can be used to match a slice or array of bytes, while square brackets `[u8]` will match either one. Empty square brackets, `[]`, will match any slice regardless of what it contains.

Preview:

* [`option -> []`](https://notriddle.com/rustdoc-demo-html-3/search-slice-array/std/index.html?search=option%20-%3E%20%5B%5D)
* [`[u8] -> str`](https://notriddle.com/rustdoc-demo-html-3/search-slice-array/std/index.html?search=%5Bu8%5D%20-%3E%20str)
* [`Box<[u8]> -> str`](https://notriddle.com/rustdoc-demo-html-3/search-slice-array/std/index.html?search=Box%3C%5Bu8%5D%3E%20-%3E%20str)

Motivation:

When type-based search was first landed, it was directly described as "incomplete". Here's [a comment] from the discussion thread:

[a comment]: #23289 (comment)

> This is looking really great, nice work! I can think of a number of cases that aren't quite covered by this, but I feel like this is a great improvement regardless and it can always be iterated on so I'm fine landing with a few known cases where it may not work :)

Filling out the missing functionality is going to mean adding support for more of Rust's [type expression] syntax, such as slices (in this PR), tuples, references, raw pointers, function pointers, and generics.

[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.
  • Loading branch information
bors committed Jun 11, 2023
2 parents 7b6093e + d3a4cd6 commit 81c02da
Show file tree
Hide file tree
Showing 8 changed files with 502 additions and 82 deletions.
5 changes: 5 additions & 0 deletions src/doc/rustdoc/src/how-to-read-rustdoc.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,11 @@ will match these queries:

But it *does not* match `Result<Vec, u8>` or `Result<u8<Vec>>`.

Function signature searches also support arrays and slices. The explicit name
`primitive:slice<u8>` and `primitive:array<u8>` can be used to match a slice
or array of bytes, while square brackets `[u8]` will match either one. Empty
square brackets, `[]`, will match any slice regardless of what it contains.

### Shortcuts

Pressing `S` while focused elsewhere on the page will move focus to the
Expand Down
4 changes: 4 additions & 0 deletions src/librustdoc/html/static/js/main.js
Original file line number Diff line number Diff line change
Expand Up @@ -1077,6 +1077,10 @@ function preLoadCss(cssUrl) {
<code>-&gt; vec</code> or <code>String, enum:Cow -&gt; bool</code>)",
"You can look for items with an exact name by putting double quotes around \
your request: <code>\"string\"</code>",
"Look for functions that accept or return \
<a href=\"https://doc.rust-lang.org/std/primitive.slice.html\">slices</a> and \
<a href=\"https://doc.rust-lang.org/std/primitive.array.html\">arrays</a> by writing \
square brackets (e.g., <code>-&gt; [u8]</code> or <code>[] -&gt; Option</code>)",
"Look for items inside another one by searching for a path: <code>vec::Vec</code>",
].map(x => "<p>" + x + "</p>").join("");
const div_infos = document.createElement("div");
Expand Down
Loading

0 comments on commit 81c02da

Please sign in to comment.