Repository navigation
rustdoc: Tracking issue for generating links to definitions on source code pages #89095
Description
This is a tracking issue for generating links to definitions on source code pages.
The feature can be enabled by passing --generate-link-to-definition -Zunstable-options to a nightly rustdoc.
Note
Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports.
Instead, open a dedicated issue for the specific matter or post in the #t-rustdoc Zulip channel.
Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.
Outstanding work
- Improve "jump links" UI: for now it's highlighted background but it was suggested we could try an "underline dotted": Consider styling go-to-definition links using faint underline #88120
- Add support to go to both source definition and documentation page (if available!). We could do it by adding a popup when hovering the item. (Provide doc links at item definitions on source pages #89157)
- Make all links go to source location, not documentation (currently, external types link to documentation)
Steps
To go through stabilization, we will gradually enable it in different places:
- Enable it by default on the compiler docs (Enable --generate-link-to-definition for rustc's docs #88292 and Enable "generate-link-to-definition" option on rust tools docs as well #89217)
- Enable it by default on the std docs
- Enable the feature by default (on nightly only) and remove the flag.
- Send the stabilization PR.
Implementation history
FIXME: Likely missing some PRs.
- Generate links to definition in rustdoc source code pages #84176
- Add links for primitives in "jump to definition" feature #88033
- Add macro support in jump to definition feature #91264
- Enable "jump to def" feature on patterns #134216
- [rustdoc] Add support for associated items in "jump to def" feature #135771
Activity
jyn514 commentedon Sep 24, 2021
I think we should not do this, this is exactly how we got in trouble with intra-doc links (see #63305). Instead we should just enable it by default at the same time we remove the flag and stabilize the feature.
GuillaumeGomez commentedon Sep 24, 2021
This is a very good point. I had in mind that maybe people would want to disable it but I guess we can always add it later on if the needs appear.
Rollup merge of rust-lang#89217 - GuillaumeGomez:generate-link-to-def…
Rollup merge of rust-lang#89217 - GuillaumeGomez:generate-link-to-def…
rust: enable rustdoc's `--generate-link-to-definition`
rust: enable rustdoc's `--generate-link-to-definition`
Rollup merge of rust-lang#134216 - GuillaumeGomez:jump-to-def-pats, r…
Rollup merge of rust-lang#134216 - GuillaumeGomez:jump-to-def-pats, r…
Unrolled build for rust-lang#134216
[-]Tracking Issue for "jump to definition"[/-][+]rustdoc: Tracking issue for generating links to definitions on source pages[/+][-]rustdoc: Tracking issue for generating links to definitions on source pages[/-][+]rustdoc: Tracking issue for generating links to definitions on source code pages[/+]