rustdoc_json: improve handling of generic args #142502
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rustbot
added
A-rustdoc-json
|
rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing |
|
Local measurements indicate some sub-1% instruction count improvements, and some max-rss improvements of up to 2%. |
|
☔ The latest upstream changes (presumably #142335) made this pull request unmergeable. Please resolve the merge conflicts. |
nnethercote
force-pushed
the
rustdoc-json-GenericArgs
branch
from
f232c4e to
27eee69
Compare
There was a problem hiding this comment.
Behavioral changes make sense, but all of them needs tests.
They live in tests/rustdoc-json. Sadly, I've not finished the docs for it yet (rust-lang/rustc-dev-guide#2422), but there's a draft here
type/generic_default.rs and gats.rs are probably good examples
aDotInTheVoid
added
S-waiting-on-author
A lot of these are large! Lots of room for improvement in the future.
A path without generic args, like `Reader`, currently has JSON produced
like this:
```
{"path":"Reader","id":286,"args":{"angle_bracketed":{"args":[],"constraints":[]}}}
```
Even though `types::Path::args` is `Option` and allows for "no args",
instead it gets represented as "empty args". (More like `Reader<>` than
`Reader`.)
This is due to a problem in `clean::Path::from_clean`. It only produces
`None` if the path is an empty string. This commit changes it to also
produce `None` if there are no generic args. The example above becomes:
```
{"path":"Reader","id":286,"args":null}
```
I looked at a few examples and saw this reduce the size of the JSON
output by 3-9%.
The commit also adds an assertion that non-final segments don't have any
generics; something the old code was implicitly relying on.
Note: the original sin here is that `clean::PathSegment::args` is not an
`Option`, unlike `{ast,hir}::PathSegment::args`. I want to fix that, but
it can be done separately.
As per the previous commit, generic args here can only appear on the final segment. So make the comments obey that constraint.
They show up in three places: once as `Option<Box<GenericArgs>>`, once
as `Box<GenericArgs>`, and once as `GenericArgs`. The first option is
best. It is more compact because generic args are often missing. This
commit changes the latter two to the former.
Example output, before and after, for the `AssocItemConstraint` change:
```
{"name":"Offset","args":{"angle_bracketed":{"args":[],"constraints":[]}},"binding":{...}}
{"name":"Offset","args":null,"binding":{...}}
```
Example output, before and after, for the `Type::QualifiedPath` change:
```
{"qualified_path":{"name":"Offset","args":{"angle_bracketed":{"args":[],"constraints":[]}}, ...}}
{"qualified_path":{"name":"Offset","args":null, ...}}
```
This reduces JSON output size, but not by much (e.g. 0.5%), because
`AssocItemConstraint` and `Type::QualifiedPath` are uncommon.
nnethercote
force-pushed
the
rustdoc-json-GenericArgs
branch
from
27eee69 to
f3c20ca
Compare
|
These commits modify Please ensure that if you've changed the output:
|
|
I added a test as a separate commit early in the sequence, so the changes to @rustbot ready |
rustbot
added
S-waiting-on-review
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR fixes some inconsistencies and inefficiencies in how generic args are handled by rustdoc-json-types.
r? @aDotInTheVoid