mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-23 15:23:46 +00:00
d5fd88cb85
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<T></code> and/or <code>primitive:array<T></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<T></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. |
||
|---|---|---|
| .. | ||
| auxiliary | ||
| assoc-type-backtrack.js | ||
| assoc-type-backtrack.rs | ||
| assoc-type-loop.js | ||
| assoc-type-loop.rs | ||
| assoc-type.js | ||
| assoc-type.rs | ||
| basic.js | ||
| basic.rs | ||
| big-result.js | ||
| big-result.rs | ||
| doc-alias-filter-out.js | ||
| doc-alias-filter-out.rs | ||
| doc-alias-filter.js | ||
| doc-alias-filter.rs | ||
| doc-alias-whitespace.js | ||
| doc-alias-whitespace.rs | ||
| doc-alias.js | ||
| doc-alias.rs | ||
| enum-variant-not-type.js | ||
| enum-variant-not-type.rs | ||
| exact-match.js | ||
| exact-match.rs | ||
| foreign-type-path.js | ||
| foreign-type-path.rs | ||
| full-path-function.js | ||
| full-path-function.rs | ||
| gat.js | ||
| gat.rs | ||
| generics2.js | ||
| generics2.rs | ||
| generics-impl.js | ||
| generics-impl.rs | ||
| generics-match-ambiguity.js | ||
| generics-match-ambiguity.rs | ||
| generics-multi-trait.js | ||
| generics-multi-trait.rs | ||
| generics-nested.js | ||
| generics-nested.rs | ||
| generics-trait.js | ||
| generics-trait.rs | ||
| generics-unbox.js | ||
| generics-unbox.rs | ||
| generics.js | ||
| generics.rs | ||
| impl-trait.js | ||
| impl-trait.rs | ||
| macro-search.js | ||
| macro-search.rs | ||
| module-substring.js | ||
| module-substring.rs | ||
| nested-unboxed.js | ||
| nested-unboxed.rs | ||
| never-search.js | ||
| never-search.rs | ||
| path-maxeditdistance.js | ||
| path-maxeditdistance.rs | ||
| path-ordering.js | ||
| path-ordering.rs | ||
| primitive.js | ||
| primitive.rs | ||
| prototype.js | ||
| prototype.rs | ||
| raw-pointer.js | ||
| raw-pointer.rs | ||
| reexport.js | ||
| reexport.rs | ||
| search-bag-semantics.js | ||
| search-bag-semantics.rs | ||
| search-method-disambiguate.js | ||
| search-method-disambiguate.rs | ||
| search-non-local-trait-impl.js | ||
| search-non-local-trait-impl.rs | ||
| search-short-types.js | ||
| search-short-types.rs | ||
| slice-array.js | ||
| slice-array.rs | ||
| struct-like-variant.js | ||
| struct-like-variant.rs | ||
| substring.js | ||
| substring.rs | ||
| summaries.js | ||
| summaries.rs | ||
| trait-methods.js | ||
| trait-methods.rs | ||
| tuple-unit.js | ||
| tuple-unit.rs | ||
| type-parameters.js | ||
| type-parameters.rs | ||
| where-clause.js | ||
| where-clause.rs | ||