rustdoc: update book with info on type bindings

rust-lang · bors · Nov 21, 2023 · Sep 23, 2023 · Sep 23, 2023 · Nov 20, 2023
commit acc74c085d4b3d21c537f5301f088996227586ae
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 -> vec&filter-crate=std
 [`vec, vec -> bool`]: ../../std/vec/struct.Vec.html?search=vec, vec -> bool&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 -> !&filter-crate=std
 [stdoutu8]: ../../std/vec/struct.Vec.html?search=stdout, [u8]&filter-crate=std
 [iterasslice]: ../../std/vec/struct.Vec.html?search=vec::intoiter<T> -> [T]&filter-crate=std
 [iterreduce]: ../../std/index.html?search=iterator<T>, fnmut -> T&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