Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

rustdoc: add support for type filters in arguments and generics #108629

Merged
merged 2 commits into from
Mar 24, 2023
Merged

rustdoc: add support for type filters in arguments and generics #108629

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e600c0b
rustdoc: add support for type filters in arguments and generics
notriddle Mar 1, 2023
cae4385
doc: add generics improvements to rustdoc book
notriddle Mar 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions src/doc/rustdoc/src/how-to-read-rustdoc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,13 +80,20 @@ functions, and "In Return Types" shows matches in the return types of functions.
Both are very useful when looking for a function whose name you can't quite
bring to mind when you know the type you have or want.

When typing in the search bar, you can prefix your search term with a type
followed by a colon (such as `mod:`) to restrict the results to just that
kind of item. (The available items are listed in the help popup.)

Searching for `println!` will search for a macro named `println`, just like
Names in the search interface can be prefixed with an item type followed by a
colon (such as `mod:`) to restrict the results to just that kind of item. Also,
searching for `println!` will search for a macro named `println`, just like
searching for `macro:println` does.

Function signature searches can query generics, wrapped in angle brackets, and
traits are normalized like types in the search engine. 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`
* `trait:Iterator<primitive:u32> -> primitive:usize`
* `Iterator -> usize`

### Changing displayed theme

You can change the displayed theme by opening the settings menu (the gear
Expand Down
164 changes: 111 additions & 53 deletions src/librustdoc/html/static/js/search.js
View file
Open in desktop

Large diffs are not rendered by default.

11 changes: 9 additions & 2 deletions src/tools/rustdoc-js/tester.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,11 +79,18 @@ function checkNeededFields(fullPath, expected, error_text, queryName, position)
"foundElems",
"original",
"returned",
"typeFilter",
"userQuery",
"error",
];
} else if (fullPath.endsWith("elems") || fullPath.endsWith("generics")) {
} else if (fullPath.endsWith("elems") || fullPath.endsWith("returned")) {
fieldsToCheck = [
"name",
"fullPath",
"pathWithoutLast",
"pathLast",
"generics",
];
} else if (fullPath.endsWith("generics")) {
fieldsToCheck = [
"name",
"fullPath",
Expand Down
58 changes: 13 additions & 45 deletions tests/rustdoc-js-std/parser-errors.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ const QUERY = [
"a b:",
"a (b:",
"_:",
"_:a",
"a-bb",
"a>bb",
"ab'",
Expand Down Expand Up @@ -48,7 +49,6 @@ const PARSED = [
foundElems: 0,
original: "<P>",
returned: [],
typeFilter: -1,
userQuery: "<p>",
error: "Found generics without a path",
},
Expand All @@ -57,7 +57,6 @@ const PARSED = [
foundElems: 0,
original: "-> <P>",
returned: [],
typeFilter: -1,
userQuery: "-> <p>",
error: "Found generics without a path",
},
Expand All @@ -66,7 +65,6 @@ const PARSED = [
foundElems: 0,
original: "a<\"P\">",
returned: [],
typeFilter: -1,
userQuery: "a<\"p\">",
error: "Unexpected `\"` in generics",
},
Expand All @@ -75,7 +73,6 @@ const PARSED = [
foundElems: 0,
original: "\"P\" \"P\"",
returned: [],
typeFilter: -1,
userQuery: "\"p\" \"p\"",
error: "Cannot have more than one literal search element",
},
Expand All @@ -84,7 +81,6 @@ const PARSED = [
foundElems: 0,
original: "P \"P\"",
returned: [],
typeFilter: -1,
userQuery: "p \"p\"",
error: "Cannot use literal search when there is more than one element",
},
Expand All @@ -93,7 +89,6 @@ const PARSED = [
foundElems: 0,
original: "\"p\" p",
returned: [],
typeFilter: -1,
userQuery: "\"p\" p",
error: "You cannot have more than one element if you use quotes",
},
Expand All @@ -102,7 +97,6 @@ const PARSED = [
foundElems: 0,
original: "\"const\": p",
returned: [],
typeFilter: -1,
userQuery: "\"const\": p",
error: "You cannot use quotes on type filter",
},
Expand All @@ -111,16 +105,14 @@ const PARSED = [
foundElems: 0,
original: "a<:a>",
returned: [],
typeFilter: -1,
userQuery: "a<:a>",
error: "Unexpected `:` after `<`",
error: "Expected type filter before `:`",
},
{
elems: [],
foundElems: 0,
original: "a<::a>",
returned: [],
typeFilter: -1,
userQuery: "a<::a>",
error: "Unexpected `::`: paths cannot start with `::`",
},
Expand All @@ -129,7 +121,6 @@ const PARSED = [
foundElems: 0,
original: "((a))",
returned: [],
typeFilter: -1,
userQuery: "((a))",
error: "Unexpected `(`",
},
Expand All @@ -138,7 +129,6 @@ const PARSED = [
foundElems: 0,
original: "(p -> p",
returned: [],
typeFilter: -1,
userQuery: "(p -> p",
error: "Unexpected `(`",
},
Expand All @@ -147,7 +137,6 @@ const PARSED = [
foundElems: 0,
original: "::a::b",
returned: [],
typeFilter: -1,
userQuery: "::a::b",
error: "Paths cannot start with `::`",
},
Expand All @@ -156,7 +145,6 @@ const PARSED = [
foundElems: 0,
original: "a::::b",
returned: [],
typeFilter: -1,
userQuery: "a::::b",
error: "Unexpected `::::`",
},
Expand All @@ -165,7 +153,6 @@ const PARSED = [
foundElems: 0,
original: "a::b::",
returned: [],
typeFilter: -1,
userQuery: "a::b::",
error: "Paths cannot end with `::`",
},
Expand All @@ -174,7 +161,6 @@ const PARSED = [
foundElems: 0,
original: ":a",
returned: [],
typeFilter: -1,
userQuery: ":a",
error: "Expected type filter before `:`",
},
Expand All @@ -183,16 +169,14 @@ const PARSED = [
foundElems: 0,
original: "a b:",
returned: [],
typeFilter: -1,
userQuery: "a b:",
error: "Unexpected `:`",
error: "Unexpected `:` (expected path after type filter)",
},
{
elems: [],
foundElems: 0,
original: "a (b:",
returned: [],
typeFilter: -1,
userQuery: "a (b:",
error: "Unexpected `(`",
},
Expand All @@ -201,16 +185,22 @@ const PARSED = [
foundElems: 0,
original: "_:",
returned: [],
typeFilter: -1,
userQuery: "_:",
error: "Unexpected `:` (expected path after type filter)",
},
{
elems: [],
foundElems: 0,
original: "_:a",
returned: [],
userQuery: "_:a",
error: "Unknown type filter `_`",
},
{
elems: [],
foundElems: 0,
original: "a-bb",
returned: [],
typeFilter: -1,
userQuery: "a-bb",
error: "Unexpected `-` (did you mean `->`?)",
},
Expand All @@ -219,7 +209,6 @@ const PARSED = [
foundElems: 0,
original: "a>bb",
returned: [],
typeFilter: -1,
userQuery: "a>bb",
error: "Unexpected `>` (did you mean `->`?)",
},
Expand All @@ -228,7 +217,6 @@ const PARSED = [
foundElems: 0,
original: "ab'",
returned: [],
typeFilter: -1,
userQuery: "ab'",
error: "Unexpected `'`",
},
Expand All @@ -237,7 +225,6 @@ const PARSED = [
foundElems: 0,
original: "a->",
returned: [],
typeFilter: -1,
userQuery: "a->",
error: "Expected at least one item after `->`",
},
Expand All @@ -246,7 +233,6 @@ const PARSED = [
foundElems: 0,
original: '"p" <a>',
returned: [],
typeFilter: -1,
userQuery: '"p" <a>',
error: "Found generics without a path",
},
Expand All @@ -255,7 +241,6 @@ const PARSED = [
foundElems: 0,
original: '"p" a<a>',
returned: [],
typeFilter: -1,
userQuery: '"p" a<a>',
error: "You cannot have more than one element if you use quotes",
},
Expand All @@ -264,7 +249,6 @@ const PARSED = [
foundElems: 0,
original: 'a,<',
returned: [],
typeFilter: -1,
userQuery: 'a,<',
error: 'Found generics without a path',
},
Expand All @@ -273,7 +257,6 @@ const PARSED = [
foundElems: 0,
original: 'aaaaa<>b',
returned: [],
typeFilter: -1,
userQuery: 'aaaaa<>b',
error: 'Expected `,`, ` `, `:` or `->`, found `b`',
},
Expand All @@ -282,16 +265,14 @@ const PARSED = [
foundElems: 0,
original: 'fn:aaaaa<>b',
returned: [],
typeFilter: -1,
userQuery: 'fn:aaaaa<>b',
error: 'Expected `,`, ` ` or `->`, found `b`',
error: 'Expected `,`, ` `, `:` or `->`, found `b`',
},
{
elems: [],
foundElems: 0,
original: '->a<>b',
returned: [],
typeFilter: -1,
userQuery: '->a<>b',
error: 'Expected `,` or ` `, found `b`',
},
Expand All @@ -300,7 +281,6 @@ const PARSED = [
foundElems: 0,
original: 'a<->',
returned: [],
typeFilter: -1,
userQuery: 'a<->',
error: 'Unexpected `-` after `<`',
},
Expand All @@ -309,7 +289,6 @@ const PARSED = [
foundElems: 0,
original: 'a:: a',
returned: [],
typeFilter: -1,
userQuery: 'a:: a',
error: 'Paths cannot end with `::`',
},
Expand All @@ -318,7 +297,6 @@ const PARSED = [
foundElems: 0,
original: 'a ::a',
returned: [],
typeFilter: -1,
userQuery: 'a ::a',
error: 'Paths cannot start with `::`',
},
Expand All @@ -327,16 +305,14 @@ const PARSED = [
foundElems: 0,
original: "a<a>:",
returned: [],
typeFilter: -1,
userQuery: "a<a>:",
error: 'Unexpected `:`',
error: 'Unexpected `<` in type filter',
},
{
elems: [],
foundElems: 0,
original: "a<>:",
returned: [],
typeFilter: -1,
userQuery: "a<>:",
error: 'Unexpected `<` in type filter',
},
Expand All @@ -345,7 +321,6 @@ const PARSED = [
foundElems: 0,
original: "a,:",
returned: [],
typeFilter: -1,
userQuery: "a,:",
error: 'Unexpected `,` in type filter',
},
Expand All @@ -354,7 +329,6 @@ const PARSED = [
foundElems: 0,
original: "a<> :",
returned: [],
typeFilter: -1,
userQuery: "a<> :",
error: 'Unexpected `<` in type filter',
},
Expand All @@ -363,7 +337,6 @@ const PARSED = [
foundElems: 0,
original: "mod : :",
returned: [],
typeFilter: -1,
userQuery: "mod : :",
error: 'Unexpected `:`',
},
Expand All @@ -372,7 +345,6 @@ const PARSED = [
foundElems: 0,
original: "a!a",
returned: [],
typeFilter: -1,
userQuery: "a!a",
error: 'Unexpected `!`: it can only be at the end of an ident',
},
Expand All @@ -381,7 +353,6 @@ const PARSED = [
foundElems: 0,
original: "a!!",
returned: [],
typeFilter: -1,
userQuery: "a!!",
error: 'Cannot have more than one `!` in an ident',
},
Expand All @@ -390,7 +361,6 @@ const PARSED = [
foundElems: 0,
original: "mod:a!",
returned: [],
typeFilter: -1,
userQuery: "mod:a!",
error: 'Invalid search type: macro `!` and `mod` both specified',
},
Expand All @@ -399,7 +369,6 @@ const PARSED = [
foundElems: 0,
original: "a!::a",
returned: [],
typeFilter: -1,
userQuery: "a!::a",
error: 'Cannot have associated items in macros',
},
Expand All @@ -408,7 +377,6 @@ const PARSED = [
foundElems: 0,
original: "a<",
returned: [],
typeFilter: -1,
userQuery: "a<",
error: "Unclosed `<`",
},
Expand Down
Loading