Rollup merge of #124148 - notriddle:notriddle/reference, r=GuillaumeGomez

rustdoc-search: search for references

This feature extends rustdoc with syntax and search index information for searching borrow references. Part of https://github.com/rust-lang/rust/issues/60485

## Preview

- [`&mut`](https://notriddle.com/rustdoc-html-demo-11/reference/std/index.html?search=%26mut)
- [`&Option<T> -> Option<&T>`](https://notriddle.com/rustdoc-html-demo-11/reference/std/index.html?search=%26Option%3CT%3E%20-%3E%20Option%3C%26T%3E)
- [`&mut Option<T> -> Option<&mut T>`](https://notriddle.com/rustdoc-html-demo-11/reference/std/index.html?search=%26mut%20Option%3CT%3E%20-%3E%20Option%3C%26mut%20T%3E)

Updated chapter of the book: https://notriddle.com/rustdoc-html-demo-11/reference/rustdoc/read-documentation/search.html

## Motivation

See https://github.com/rust-lang/rust/pull/119676

## Guide-level explanation

You can't search by lifetimes, but other than that it's the same syntax references normally use.

## Reference-level description

<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><code>(T, U -> V, W)</code></td>
    <td><code>fn(T, U) -> (V, W)</code>, Fn, FnMut, and FnOnce</td>
  </tr>
  <tr><td colspan="2">New additions with this PR</td></tr>
  <tr>
    <td><code>&</code></td>
    <td><code>primitive:reference</td>
  </tr>
  <tr>
    <td><code>&mut</code></td>
    <td><code>primitive:reference&lt;keyword:mut&gt;</td>
  </tr>
  <tr>
    <td><code>&T</code></td>
    <td><code>primitive:reference&lt;T&gt;</td>
  </tr>
  <tr>
    <td><code>&mut T</code></td>
    <td><code>primitive:reference&lt;keyword:mut, T&gt;</td>
  </tr>
</tbody>
</table>

### Search query grammar

<code><pre><strong>borrow-ref = AMP *WS [MUT] *WS [arg]</strong>
arg = [type-filter *WS COLON *WS] (path [generics] / slice-like / tuple-like / <strong>borrow-ref</strong>)</pre></code>

```
AMP = "&"
MUT = "mut"
```

## Future direction

As described in https://github.com/rust-lang/rust/pull/118194 and https://github.com/rust-lang/rust/pull/119676

* The remaining type expression grammar (this is another step in the type expression grammar: `ReferenceType` is now supported)
* Search subtyping and traits

1 files changed, 527 insertions, 0 deletions

diff --git a/tests/rustdoc-js-std/parser-reference.js b/tests/rustdoc-js-std/parser-reference.js
new file mode 100644
index 00000000000..6b1250146be
--- /dev/null
+++ b/tests/rustdoc-js-std/parser-reference.js
@@ -0,0 +1,527 @@
+const PARSED = [
+    {
+        query: '&[',
+        elems: [],
+        foundElems: 0,
+        original: '&[',
+        returned: [],
+        userQuery: '&[',
+        error: 'Unclosed `[`',
+    },
+    {
+        query: '[&',
+        elems: [],
+        foundElems: 0,
+        original: '[&',
+        returned: [],
+        userQuery: '[&',
+        error: 'Unclosed `[`',
+    },
+    {
+        query: '&&&D, []',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "reference",
+                        fullPath: ["reference"],
+                        pathWithoutLast: [],
+                        pathLast: "reference",
+                        generics: [
+                            {
+                                name: "reference",
+                                fullPath: ["reference"],
+                                pathWithoutLast: [],
+                                pathLast: "reference",
+                                generics: [
+                                    {
+                                        name: "d",
+                                        fullPath: ["d"],
+                                        pathWithoutLast: [],
+                                        pathLast: "d",
+                                        generics: [],
+                                        typeFilter: -1,
+                                    },
+                                ],
+                                typeFilter: 1,
+                            },
+                        ],
+                        typeFilter: 1,
+                    },
+                ],
+                typeFilter: 1,
+            },
+            {
+                name: "[]",
+                fullPath: ["[]"],
+                pathWithoutLast: [],
+                pathLast: "[]",
+                generics: [],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 2,
+        original: '&&&D, []',
+        returned: [],
+        userQuery: '&&&d, []',
+        error: null,
+    },
+    {
+        query: '&&&[D]',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "reference",
+                        fullPath: ["reference"],
+                        pathWithoutLast: [],
+                        pathLast: "reference",
+                        generics: [
+                            {
+                                name: "reference",
+                                fullPath: ["reference"],
+                                pathWithoutLast: [],
+                                pathLast: "reference",
+                                generics: [
+                                    {
+                                        name: "[]",
+                                        fullPath: ["[]"],
+                                        pathWithoutLast: [],
+                                        pathLast: "[]",
+                                        generics: [
+                                            {
+                                                name: "d",
+                                                fullPath: ["d"],
+                                                pathWithoutLast: [],
+                                                pathLast: "d",
+                                                generics: [],
+                                                typeFilter: -1,
+                                            },
+                                        ],
+                                        typeFilter: 1,
+                                    },
+                                ],
+                                typeFilter: 1,
+                            },
+                        ],
+                        typeFilter: 1,
+                    },
+                ],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 1,
+        original: '&&&[D]',
+        returned: [],
+        userQuery: '&&&[d]',
+        error: null,
+    },
+    {
+        query: '&',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 1,
+        original: '&',
+        returned: [],
+        userQuery: '&',
+        error: null,
+    },
+    {
+        query: '&mut',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "mut",
+                        fullPath: ["mut"],
+                        pathWithoutLast: [],
+                        pathLast: "mut",
+                        generics: [],
+                        typeFilter: 0,
+                    },
+                ],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 1,
+        original: '&mut',
+        returned: [],
+        userQuery: '&mut',
+        error: null,
+    },
+    {
+        query: '&,u8',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [],
+                typeFilter: 1,
+            },
+            {
+                name: "u8",
+                fullPath: ["u8"],
+                pathWithoutLast: [],
+                pathLast: "u8",
+                generics: [],
+                typeFilter: -1,
+            },
+        ],
+        foundElems: 2,
+        original: "&,u8",
+        returned: [],
+        userQuery: "&,u8",
+        error: null,
+    },
+    {
+        query: '&mut,u8',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "mut",
+                        fullPath: ["mut"],
+                        pathWithoutLast: [],
+                        pathLast: "mut",
+                        generics: [],
+                        typeFilter: 0,
+                    },
+                ],
+                typeFilter: 1,
+            },
+            {
+                name: "u8",
+                fullPath: ["u8"],
+                pathWithoutLast: [],
+                pathLast: "u8",
+                generics: [],
+                typeFilter: -1,
+            },
+        ],
+        foundElems: 2,
+        original: "&mut,u8",
+        returned: [],
+        userQuery: "&mut,u8",
+        error: null,
+    },
+    {
+        query: '&u8',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "u8",
+                        fullPath: ["u8"],
+                        pathWithoutLast: [],
+                        pathLast: "u8",
+                        generics: [],
+                        typeFilter: -1,
+                    },
+                ],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 1,
+        original: "&u8",
+        returned: [],
+        userQuery: "&u8",
+        error: null,
+    },
+    {
+        query: '&u8<u8>',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "u8",
+                        fullPath: ["u8"],
+                        pathWithoutLast: [],
+                        pathLast: "u8",
+                        generics: [
+                            {
+                                name: "u8",
+                                fullPath: ["u8"],
+                                pathWithoutLast: [],
+                                pathLast: "u8",
+                                generics: [],
+                                typeFilter: -1,
+                            },
+                        ],
+                        typeFilter: -1,
+                    },
+                ],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 1,
+        original: "&u8<u8>",
+        returned: [],
+        userQuery: "&u8<u8>",
+        error: null,
+    },
+    {
+        query: 'u8<&u8>',
+        elems: [
+            {
+                name: "u8",
+                fullPath: ["u8"],
+                pathWithoutLast: [],
+                pathLast: "u8",
+                generics: [
+                    {
+                        name: "reference",
+                        fullPath: ["reference"],
+                        pathWithoutLast: [],
+                        pathLast: "reference",
+                        generics: [
+                            {
+                                name: "u8",
+                                fullPath: ["u8"],
+                                pathWithoutLast: [],
+                                pathLast: "u8",
+                                generics: [],
+                                typeFilter: -1,
+                            },
+                        ],
+                        typeFilter: 1,
+                    },
+                ],
+                typeFilter: -1,
+            },
+        ],
+        foundElems: 1,
+        original: "u8<&u8>",
+        returned: [],
+        userQuery: "u8<&u8>",
+        error: null,
+    },
+    {
+        query: 'u8<&u8, u8>',
+        elems: [
+            {
+                name: "u8",
+                fullPath: ["u8"],
+                pathWithoutLast: [],
+                pathLast: "u8",
+                generics: [
+                    {
+                        name: "reference",
+                        fullPath: ["reference"],
+                        pathWithoutLast: [],
+                        pathLast: "reference",
+                        generics: [
+                            {
+                                name: "u8",
+                                fullPath: ["u8"],
+                                pathWithoutLast: [],
+                                pathLast: "u8",
+                                generics: [],
+                                typeFilter: -1,
+                            },
+                        ],
+                        typeFilter: 1,
+                    },
+                    {
+                        name: "u8",
+                        fullPath: ["u8"],
+                        pathWithoutLast: [],
+                        pathLast: "u8",
+                        generics: [],
+                        typeFilter: -1,
+                    },
+                ],
+                typeFilter: -1,
+            },
+        ],
+        foundElems: 1,
+        original: "u8<&u8, u8>",
+        returned: [],
+        userQuery: "u8<&u8, u8>",
+        error: null,
+    },
+    {
+        query: 'u8<&u8>',
+        elems: [
+            {
+                name: "u8",
+                fullPath: ["u8"],
+                pathWithoutLast: [],
+                pathLast: "u8",
+                generics: [
+                    {
+                        name: "reference",
+                        fullPath: ["reference"],
+                        pathWithoutLast: [],
+                        pathLast: "reference",
+                        generics: [
+                            {
+                                name: "u8",
+                                fullPath: ["u8"],
+                                pathWithoutLast: [],
+                                pathLast: "u8",
+                                generics: [],
+                                typeFilter: -1,
+                            },
+                        ],
+                        typeFilter: 1,
+                    },
+                ],
+                typeFilter: -1,
+            },
+        ],
+        foundElems: 1,
+        original: "u8<&u8>",
+        returned: [],
+        userQuery: "u8<&u8>",
+        error: null,
+    },
+    {
+        query: 'u8<&mut u8, u8>',
+        elems: [
+            {
+                name: "u8",
+                fullPath: ["u8"],
+                pathWithoutLast: [],
+                pathLast: "u8",
+                generics: [
+                    {
+                        name: "reference",
+                        fullPath: ["reference"],
+                        pathWithoutLast: [],
+                        pathLast: "reference",
+                        generics: [
+                            {
+                                name: "mut",
+                                fullPath: ["mut"],
+                                pathWithoutLast: [],
+                                pathLast: "mut",
+                                generics: [],
+                                typeFilter: 0,
+                            },
+                            {
+                                name: "u8",
+                                fullPath: ["u8"],
+                                pathWithoutLast: [],
+                                pathLast: "u8",
+                                generics: [],
+                                typeFilter: -1,
+                            },
+                        ],
+                        typeFilter: 1,
+                    },
+                    {
+                        name: "u8",
+                        fullPath: ["u8"],
+                        pathWithoutLast: [],
+                        pathLast: "u8",
+                        generics: [],
+                        typeFilter: -1,
+                    },
+                ],
+                typeFilter: -1,
+            },
+        ],
+        foundElems: 1,
+        original: "u8<&mut u8, u8>",
+        returned: [],
+        userQuery: "u8<&mut u8, u8>",
+        error: null,
+    },
+    {
+        query: 'primitive:&u8',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "u8",
+                        fullPath: ["u8"],
+                        pathWithoutLast: [],
+                        pathLast: "u8",
+                        generics: [],
+                        typeFilter: -1,
+                    },
+                ],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 1,
+        original: "primitive:&u8",
+        returned: [],
+        userQuery: "primitive:&u8",
+        error: null,
+    },
+    {
+        query: 'macro:&u8',
+        elems: [],
+        foundElems: 0,
+        original: "macro:&u8",
+        returned: [],
+        userQuery: "macro:&u8",
+        error: "Invalid search type: primitive `&` and `macro` both specified",
+    },
+    {
+        query: '&macro:u8',
+        elems: [
+            {
+                name: "reference",
+                fullPath: ["reference"],
+                pathWithoutLast: [],
+                pathLast: "reference",
+                generics: [
+                    {
+                        name: "u8",
+                        fullPath: ["u8"],
+                        pathWithoutLast: [],
+                        pathLast: "u8",
+                        generics: [],
+                        typeFilter: 16,
+                    },
+                ],
+                typeFilter: 1,
+            },
+        ],
+        foundElems: 1,
+        original: "&macro:u8",
+        returned: [],
+        userQuery: "&macro:u8",
+        error: null,
+    },
+];