[rustdoc] Correctly generate path for non-local items in source code pages #120596

GuillaumeGomez · 2024-02-03T00:36:07Z

While browsing some crates using the "jump to def" feature, I realized that a lot of items didn't have a link generated. The reason is because we only cache foreign items if they appear in the documented API. This means that for the others, we need to infer them.

r? @notriddle

src/librustdoc/html/format.rs

src/librustdoc/clean/inline.rs

src/librustdoc/html/format.rs

tests/rustdoc/jump-to-non-local-method.rs

notriddle · 2024-02-03T04:18:50Z

src/librustdoc/html/format.rs

            } else {
-                return Err(HrefError::NotInExternalCache);
+                return generate_item_def_id_path(did, original_did, cx, root_path);


Is there a reason why generate_item_def_id_path can't be used all the time?

Because if a local item is not in the cache, something really strange is going on and I'm not sure whether or not we should try to get more information for it.

Just double-checked, the other reason is that the code expects local items to be allows "known" so we only use extern_locations to get information about the (foreign) crate containing the item.

I understand that extern_locations points at third-party websites, so that links to the standard library and within docs.rs work. I also understand why external_paths is separate from locally defined paths.

I'm wondering why external_paths needs to exist at all. If it needs to be cached for performance, why the map can't be lazily populated on use using this same code? Currently, it's populated by a mess of calls to record_extern_fqn, which could potentially be removed in favor of relying on the compiler more.

For now external_paths only contains foreign items exposed in the public API. It allows to prevent recomputing this path every time, so I think it's worth it to keep it. Now I suppose the question is: should we store foreign paths for "jump to def" items? The problem is that we don't have perf checks for this feature, so it' be complicated to track exactly the impact. What do you think about opening an issue to cache these paths and also update the rust perf tool to include a crate which uses this feature?

Could external_paths be computed using this same logic instead of the mess of calls to record_foreign_fqn that are used now?

I suppose it's possible. Want me to do it here or in a follow-up?

I'd like to do it as a commit on this PR. The idea is that all the existing test cases should wind up covering this code since it'll be exercised more.

After trying to figure out how to do it: f we don't have record_extern_fqn, first it means that exact_paths won't be filled anymore. It also means we need to update the Cache when it's not mutable anymore (and stored inside a Rc<> in SharedContext), which means we need to put it into a RefCell. With this approach, we need to add a method which would take a callback (because you can't return a value of RefCell from a method). But then that makes a lot of parts of the code much more tricky to handle...

GuillaumeGomez · 2024-02-05T23:13:54Z

Extended tests and fixed corner cases.

notriddle · 2024-02-07T18:16:31Z

@bors r+

bors · 2024-02-07T18:16:35Z

📌 Commit 898bb7f has been approved by notriddle

It is now in the queue for this repository.

GuillaumeGomez · 2024-02-07T19:02:10Z

@bors rollup

…al-link, r=notriddle [rustdoc] Correctly generate path for non-local items in source code pages While browsing some crates using the "jump to def" feature, I realized that a lot of items didn't have a link generated. The reason is because we only cache foreign items if they appear in the documented API. This means that for the others, we need to infer them. r? `@notriddle`

…iaskrgr Rollup of 8 pull requests Successful merges: - rust-lang#119592 (resolve: Unload speculatively resolved crates before freezing cstore) - rust-lang#120103 (Make it so that async-fn-in-trait is compatible with a concrete future in implementation) - rust-lang#120206 (hir: Make sure all `HirId`s have corresponding HIR `Node`s) - rust-lang#120214 (match lowering: consistently lower bindings deepest-first) - rust-lang#120596 ([rustdoc] Correctly generate path for non-local items in source code pages) - rust-lang#120688 (GVN: also turn moves into copies with projections) - rust-lang#120702 (docs: also check the inline stmt during redundant link check) - rust-lang#120739 (improve pretty printing for associated items in trait objects) r? `@ghost` `@rustbot` modify labels: rollup

…al-link, r=notriddle [rustdoc] Correctly generate path for non-local items in source code pages While browsing some crates using the "jump to def" feature, I realized that a lot of items didn't have a link generated. The reason is because we only cache foreign items if they appear in the documented API. This means that for the others, we need to infer them. r? ``@notriddle``

…iaskrgr Rollup of 9 pull requests Successful merges: - rust-lang#119592 (resolve: Unload speculatively resolved crates before freezing cstore) - rust-lang#120103 (Make it so that async-fn-in-trait is compatible with a concrete future in implementation) - rust-lang#120206 (hir: Make sure all `HirId`s have corresponding HIR `Node`s) - rust-lang#120214 (match lowering: consistently lower bindings deepest-first) - rust-lang#120596 ([rustdoc] Correctly generate path for non-local items in source code pages) - rust-lang#120688 (GVN: also turn moves into copies with projections) - rust-lang#120727 (exhaustiveness: Prefer "`0..MAX` not covered" to "`_` not covered") - rust-lang#120734 (Add `SubdiagnosticMessageOp` as a trait alias.) - rust-lang#120739 (improve pretty printing for associated items in trait objects) r? `@ghost` `@rustbot` modify labels: rollup

matthiaskrgr · 2024-02-08T08:06:07Z

@bors r-
#120766 (comment)

GuillaumeGomez · 2024-02-08T10:46:23Z

Strange. Rebased and re-ran tests locally without any issue. Maybe a rebase was missing.

@bors r=notriddle

bors · 2024-02-08T10:46:25Z

📌 Commit 11bd2ea has been approved by notriddle

It is now in the queue for this repository.

…al-link, r=notriddle [rustdoc] Correctly generate path for non-local items in source code pages While browsing some crates using the "jump to def" feature, I realized that a lot of items didn't have a link generated. The reason is because we only cache foreign items if they appear in the documented API. This means that for the others, we need to infer them. r? `@notriddle`

GuillaumeGomez · 2024-02-09T10:28:52Z

Seems to be exactly the same failure as last time. I don't get why it works in CI here and locally but not in rollups...

GuillaumeGomez · 2024-02-09T12:54:18Z

Well, let's try it outside of a rollup...

@bors r=notriddle

bors · 2024-02-09T12:54:20Z

📌 Commit 7940d02 has been approved by notriddle

It is now in the queue for this repository.

fmease · 2024-02-09T13:04:51Z

I'm pretty sure I know why
@bors r-

fmease · 2024-02-09T13:06:56Z

tests/rustdoc/jump-to-non-local-method.rs

+
+// @has 'src/foo/jump-to-non-local-method.rs.html'
+
+// @has - '//a[@href="https://doc.rust-lang.org/nightly/core/sync/atomic/struct.AtomicIsize.html"]' 'std::sync::atomic::AtomicIsize'


Suggested change

// @has - '//a[@href="https://doc.rust-lang.org/nightly/core/sync/atomic/struct.AtomicIsize.html"]' 'std::sync::atomic::AtomicIsize'

// @has - '//a[@href="{{channel}}/core/sync/atomic/struct.AtomicIsize.html"]' 'std::sync::atomic::AtomicIsize'

... It's so obvious I'm ashamed I didn't think about it myself...

fmease · 2024-02-09T13:07:09Z

tests/rustdoc/jump-to-non-local-method.rs

+
+// @has - '//a[@href="https://doc.rust-lang.org/nightly/core/sync/atomic/struct.AtomicIsize.html"]' 'std::sync::atomic::AtomicIsize'
+use std::sync::atomic::AtomicIsize;
+// @has - '//a[@href="https://doc.rust-lang.org/nightly/std/io/trait.Read.html"]' 'std::io::Read'


ditto et seqq.

GuillaumeGomez · 2024-02-09T13:22:28Z

This time it's safe to put back into rollup. :)

@bors r=notriddle,fmease rollup

bors · 2024-02-09T13:22:30Z

📌 Commit 14e0dab has been approved by notriddle,fmease

It is now in the queue for this repository.

…al-link, r=notriddle,fmease [rustdoc] Correctly generate path for non-local items in source code pages While browsing some crates using the "jump to def" feature, I realized that a lot of items didn't have a link generated. The reason is because we only cache foreign items if they appear in the documented API. This means that for the others, we need to infer them. r? `@notriddle`

…iaskrgr Rollup of 7 pull requests Successful merges: - rust-lang#120584 (For a rigid projection, recursively look at the self type's item bounds to fix the `associated_type_bounds` feature) - rust-lang#120589 (std::thread::available_parallelism merging linux/android/freebsd version) - rust-lang#120596 ([rustdoc] Correctly generate path for non-local items in source code pages) - rust-lang#120629 (Move some test files) - rust-lang#120846 (Update jobserver-rs to 0.1.28) - rust-lang#120850 (ast_lowering: Fix regression in `use ::{}` imports.) - rust-lang#120853 (Avoid a collection and iteration on empty passes) Failed merges: - rust-lang#120549 (modify alias-relate to also normalize ambiguous opaques) r? `@ghost` `@rustbot` modify labels: rollup

…iaskrgr Rollup of 6 pull requests Successful merges: - rust-lang#120584 (For a rigid projection, recursively look at the self type's item bounds to fix the `associated_type_bounds` feature) - rust-lang#120596 ([rustdoc] Correctly generate path for non-local items in source code pages) - rust-lang#120629 (Move some test files) - rust-lang#120846 (Update jobserver-rs to 0.1.28) - rust-lang#120850 (ast_lowering: Fix regression in `use ::{}` imports.) - rust-lang#120853 (Avoid a collection and iteration on empty passes) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#120596 - GuillaumeGomez:jump-to-def-non-local-link, r=notriddle,fmease [rustdoc] Correctly generate path for non-local items in source code pages While browsing some crates using the "jump to def" feature, I realized that a lot of items didn't have a link generated. The reason is because we only cache foreign items if they appear in the documented API. This means that for the others, we need to infer them. r? ``@notriddle``

rustbot assigned notriddle Feb 3, 2024

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Feb 3, 2024

fmease reviewed Feb 3, 2024

View reviewed changes

src/librustdoc/html/format.rs Outdated Show resolved Hide resolved

notriddle requested changes Feb 3, 2024

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 3, 2024

GuillaumeGomez force-pushed the jump-to-def-non-local-link branch from 5613719 to 898bb7f Compare February 5, 2024 22:50

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 7, 2024

matthiaskrgr mentioned this pull request Feb 7, 2024

Rollup of 8 pull requests #120755

Closed

matthiaskrgr mentioned this pull request Feb 8, 2024

Rollup of 9 pull requests #120766

Closed

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 8, 2024

GuillaumeGomez force-pushed the jump-to-def-non-local-link branch from 898bb7f to 11bd2ea Compare February 8, 2024 10:45

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 8, 2024

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 9, 2024

GuillaumeGomez added 2 commits February 9, 2024 11:29

Correctly generate path for non-local items in source code pages

f0d002b

Add regression test for non local items link generation

f3c2483

GuillaumeGomez force-pushed the jump-to-def-non-local-link branch from 11bd2ea to 7940d02 Compare February 9, 2024 10:29

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 9, 2024

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 9, 2024

fmease requested changes Feb 9, 2024

View reviewed changes

Unify item relative path computation in one function

14e0dab

GuillaumeGomez force-pushed the jump-to-def-non-local-link branch from 7940d02 to 14e0dab Compare February 9, 2024 13:16

fmease approved these changes Feb 9, 2024

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 9, 2024

matthiaskrgr mentioned this pull request Feb 9, 2024

Rollup of 7 pull requests #120861

Closed

matthiaskrgr mentioned this pull request Feb 9, 2024

Rollup of 6 pull requests #120862

Merged

bors merged commit c06199f into rust-lang:master Feb 10, 2024
11 checks passed

rustbot added this to the 1.78.0 milestone Feb 10, 2024

GuillaumeGomez deleted the jump-to-def-non-local-link branch February 10, 2024 10:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[rustdoc] Correctly generate path for non-local items in source code pages #120596

[rustdoc] Correctly generate path for non-local items in source code pages #120596

GuillaumeGomez commented Feb 3, 2024

notriddle Feb 3, 2024

GuillaumeGomez Feb 3, 2024

GuillaumeGomez Feb 5, 2024

notriddle Feb 6, 2024 •

edited

Loading

GuillaumeGomez Feb 6, 2024

notriddle Feb 6, 2024

GuillaumeGomez Feb 6, 2024

notriddle Feb 6, 2024

GuillaumeGomez Feb 7, 2024

GuillaumeGomez commented Feb 5, 2024

notriddle commented Feb 7, 2024

bors commented Feb 7, 2024

GuillaumeGomez commented Feb 7, 2024

matthiaskrgr commented Feb 8, 2024

GuillaumeGomez commented Feb 8, 2024

bors commented Feb 8, 2024

GuillaumeGomez commented Feb 9, 2024

GuillaumeGomez commented Feb 9, 2024

bors commented Feb 9, 2024

fmease commented Feb 9, 2024

fmease Feb 9, 2024

GuillaumeGomez Feb 9, 2024

fmease Feb 9, 2024

GuillaumeGomez commented Feb 9, 2024 •

edited

Loading

bors commented Feb 9, 2024


		// @has 'src/foo/jump-to-non-local-method.rs.html'

		// @has - '//a[@href="https://doc.rust-lang.org/nightly/core/sync/atomic/struct.AtomicIsize.html"]' 'std::sync::atomic::AtomicIsize'

	// @has - '//a[@href="https://doc.rust-lang.org/nightly/core/sync/atomic/struct.AtomicIsize.html"]' 'std::sync::atomic::AtomicIsize'
	// @has - '//a[@href="{{channel}}/core/sync/atomic/struct.AtomicIsize.html"]' 'std::sync::atomic::AtomicIsize'

[rustdoc] Correctly generate path for non-local items in source code pages #120596

[rustdoc] Correctly generate path for non-local items in source code pages #120596

Conversation

GuillaumeGomez commented Feb 3, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

notriddle Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GuillaumeGomez commented Feb 5, 2024

notriddle commented Feb 7, 2024

bors commented Feb 7, 2024

GuillaumeGomez commented Feb 7, 2024

matthiaskrgr commented Feb 8, 2024

GuillaumeGomez commented Feb 8, 2024

bors commented Feb 8, 2024

GuillaumeGomez commented Feb 9, 2024

GuillaumeGomez commented Feb 9, 2024

bors commented Feb 9, 2024

fmease commented Feb 9, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GuillaumeGomez commented Feb 9, 2024 • edited Loading

bors commented Feb 9, 2024

notriddle Feb 6, 2024 •

edited

Loading

GuillaumeGomez commented Feb 9, 2024 •

edited

Loading