rustdoc: Parse intra-doc links using rustc_parse
#151049
Draft
+528
−367
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
Previously, these failed to resolve, despite them working for struct fields or enum variants that were behind aliases. However, there is now an inconsistency where enum variant fields behind an alias resolve to the entry on the alias's page, while enum variants and struct fields resolve to the page of the backing ADT.
The old name and API were confusing. In my opinion, looking up the type at the call site is clearer.
All the other parts of this function return the Res for the containing page, but for some reason, this returns the associated item itself. It doesn't seem to affect the behavior of rustdoc because e.g. the href functions use the parent if the DefId is for an assoc item. But it's clearer and simpler to be consistent.
This will make it significantly easier to add support for fully-qualified paths (e.g. `<Foo as Trait>::bar` and `<dyn Trait>::bar`) without duplicating logic from rustc. All paths that need type-dependent resolution -- i.e. all that are not handled by `rustc_resolve` -- are now parsed by `rustc_parse`, except for associated items on some primitives. We support non-standard Rust syntax like `!::clone` in rustdoc, so those cannot be parsed by rustc. My hope is that once fully-qualified paths are implemented, we can deprecate (but still support) this unusual syntax. As part of this change, I also fixed a pre-existing bug where links to fields of re-exported variants were not resolved. This was because we assumed that these links always had at least three path segments; this assumption is broken by re-exports.
rustbot
added
S-waiting-on-author
Member
Author
|
Blocked on #150586. |
Member
Author
|
@bors try @rust-timer queue |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
rust-bors bot
pushed a commit
that referenced
this pull request
Jan 13, 2026
rustdoc: Parse intra-doc links using `rustc_parse`
rustbot
added
the
S-waiting-on-perf
Collaborator
|
The job Click to see the possible cause of the failure (guessed by this bot) |
Contributor
This comment has been minimized.
This comment has been minimized.
Collaborator
|
Finished benchmarking commit (aad88b3): comparison URL. Overall result: ❌ regressions - BENCHMARK(S) FAILEDBenchmarking this pull request means it may be perf-sensitive – we'll automatically label it not fit for rolling up. You can override this, but we strongly advise not to, due to possible changes in compiler perf. Next Steps: If you can justify the regressions found in this try perf run, please do so in sufficient writing along with @bors rollup=never ❗ ❗ ❗ ❗ ❗
❗ ❗ ❗ ❗ ❗ Instruction countOur most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.
Max RSS (memory usage)Results (primary -2.3%)A less reliable metric. May be of interest, but not used to determine the overall result above.
CyclesResults (primary 6.5%, secondary 2.4%)A less reliable metric. May be of interest, but not used to determine the overall result above.
Binary sizeThis benchmark run did not return any relevant results for this metric. Bootstrap: 475.39s -> 474.205s (-0.25%) |
rustbot
added
perf-regression
Member
Author
|
Ok, there are a couple of issues here:
The first could potentially be solved by not using Another complication, once we work on support for fully-qualified paths, is that Regarding backwards compatibility with keyword uses (e.g. Also, regarding backcompat with our non-standard primitive paths like Footnotes
|
Member
Author
|
cc @petrochenkov regarding the potential (minor) changes to the resolver that I mentioned above. |
petrochenkov
added
S-waiting-on-review
Member
I disagree here. Writing docs should be as easy as possible, and there is possible ambiguity here. I think the right way to handle this is to allow
I'm not too sure about this. I like |
Contributor
|
Contributor
If you make compiler changes related to doc link resolution, please assign those PRs to me |
Member
Author
I assume you meant there is no possible ambiguity. I initially thought that as well, and was thinking of adding a rustc_parse flag to allow keywords, but it's actually not true that there's no ambiguity. For example, fully-qualified paths use the Also, using keywords as item names is quite rare because it's a pain for people to write |
Member
Yes, forgot the And good catch for the |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
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.
Fixes #151030.
This will make it significantly easier to add support for
fully-qualified paths (e.g.
<Foo as Trait>::barand<dyn Trait>::bar)without duplicating logic from rustc. All paths that need
type-dependent resolution -- i.e. all that are not handled by
rustc_resolve-- are now parsed byrustc_parse, except forassociated items on some primitives. We support non-standard Rust syntax
like
!::clonein rustdoc, so those cannot be parsed by rustc. My hopeis that once fully-qualified paths are implemented, we can deprecate
(but still support) this unusual syntax.
As part of this change, I also fixed a pre-existing bug where links to
fields of re-exported variants were not resolved. This was because we
assumed that these links always had at least three path segments; this
assumption is broken by re-exports.
r? @GuillaumeGomez