rustdoc: Tracking issue for generating links to definitions on source code pages

[GuillaumeGomez]

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

[jyn514]

Enable the feature by default (on nightly only) and reverse the flag (so that it disables instead of enabling).

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]

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.