rustdoc: update book with info on type bindings

notriddle · notriddle · commit acc74c085d4b · 2023-11-19T18:54:36.000-07:00
diff --git a/src/doc/rustdoc/src/read-documentation/search.md b/src/doc/rustdoc/src/read-documentation/search.md
@@ -72,6 +72,7 @@ the standard library and functions that are included in the results list:
 | [`stdout, [u8]`][stdoutu8] | `Stdout::write` |
 | [`any -> !`][] | `panic::panic_any` |
 | [`vec::intoiter<T> -> [T]`][iterasslice] | `IntoIter::as_slice` and `IntoIter::next_chunk` |
+| [`iterator<T>, fnmut -> T`][iterreduce] | `Iterator::reduce` and `Iterator::find` |
 
 [`usize -> vec`]: ../../std/vec/struct.Vec.html?search=usize%20-%3E%20vec&filter-crate=std
 [`vec, vec -> bool`]: ../../std/vec/struct.Vec.html?search=vec,%20vec%20-%3E%20bool&filter-crate=std
@@ -81,6 +82,7 @@ the standard library and functions that are included in the results list:
 [`any -> !`]: ../../std/vec/struct.Vec.html?search=any%20-%3E%20!&filter-crate=std
 [stdoutu8]: ../../std/vec/struct.Vec.html?search=stdout%2C%20[u8]&filter-crate=std
 [iterasslice]: ../../std/vec/struct.Vec.html?search=vec%3A%3Aintoiter<T>%20->%20[T]&filter-crate=std
+[iterreduce]: ../../std/index.html?search=iterator<T>%2C%20fnmut%20->%20T&filter-crate=std
 
 ### How type-based search works
 
@@ -95,16 +97,47 @@ After deciding which items are type parameters and which are actual types, it
 then searches by matching up the function parameters (written before the `->`)
 and the return types (written after the `->`). Type matching is order-agnostic,
 and allows items to be left out of the query, but items that are present in the
-query must be present in the function for it to match.
+query must be present in the function for it to match. The `self` parameter is
+treated the same as any other parameter, and `Self` is resolved to the
+underlying type's name.
 
 Function signature searches can query generics, wrapped in angle brackets, and
 traits will be normalized like types in the search engine if no type parameters
 match them. For example, a function with the signature
 `fn my_function<I: Iterator<Item=u32>>(input: I) -> usize`
 can be matched with the following queries:
 
-* `Iterator<u32> -> usize`
-* `Iterator -> usize`
+* `Iterator<Item=u32> -> usize`
+* `Iterator<u32> -> usize` (you can leave out the `Item=` part)
+* `Iterator -> usize` (you can leave out iterator's generic entirely)
+* `T -> usize` (you can match with a generic parameter)
+
+Each of the above queries is progressively looser, except the last one
+would not match `dyn Iterator`, since that's not a type parameter.
+
+If a bound has multiple associated types, specifying the name allows you to
+pick which one gets matched. If no name is specified, then the query will
+match of any of them. For example,
+
+```rust
+pub trait MyTrait {
+    type First;
+    type Second;
+}
+
+/// This function can be found using the following search queries:
+///
+///     MyTrait<First=u8, Second=u32> -> bool
+///     MyTrait<u32, First=u8> -> bool
+///     MyTrait<Second=u32> -> bool
+///     MyTrait<u32, u8> -> bool
+///
+/// The following queries, however, will *not* match it:
+///
+///     MyTrait<First=u32> -> bool
+///     MyTrait<u32, u32> -> bool
+pub fn my_fn(x: impl MyTrait<First=u8, Second=u32>) -> bool { true }
+```
 
 Generics and function parameters are order-agnostic, but sensitive to nesting
 and number of matches. For example, a function with the signature
@@ -134,6 +167,10 @@ Most of these limitations should be addressed in future version of Rustdoc.
     with that bound, it'll match, but `option<T> -> T where T: Default`
     cannot be precisely searched for (use `option<Default> -> Default`).
 
+  * Supertraits, type aliases, and Deref are all ignored. Search mostly
+    operates on type signatures *as written*, and not as they are
+    represented within the compiler.
+
   * Type parameters match type parameters, such that `Option<A>` matches
     `Option<T>`, but never match concrete types in function signatures.
     A trait named as if it were a type, such as `Option<Read>`, will match
@@ -183,7 +220,8 @@ slice = OPEN-SQUARE-BRACKET [ nonempty-arg-list ] CLOSE-SQUARE-BRACKET
 arg = [type-filter *WS COLON *WS] (path [generics] / slice / [!])
 type-sep = COMMA/WS *(COMMA/WS)
 nonempty-arg-list = *(type-sep) arg *(type-sep arg) *(type-sep)
-generics = OPEN-ANGLE-BRACKET [ nonempty-arg-list ] *(type-sep)
+generic-arg-list = *(type-sep) arg [ EQUAL arg ] *(type-sep arg [ EQUAL arg ]) *(type-sep)
+generics = OPEN-ANGLE-BRACKET [ generic-arg-list ] *(type-sep)
             CLOSE-ANGLE-BRACKET
 return-args = RETURN-ARROW *(type-sep) nonempty-arg-list
 
@@ -230,6 +268,7 @@ DOUBLE-COLON = "::"
 QUOTE = %x22
 COMMA = ","
 RETURN-ARROW = "->"
+EQUAL = "="
 
 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
 DIGIT = %x30-39
