Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Feb 10, 2024

Conversation

GuillaumeGomez
Copy link
Member

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 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
src/librustdoc/clean/inline.rs Show resolved Hide resolved
src/librustdoc/html/format.rs Show resolved Hide resolved
tests/rustdoc/jump-to-non-local-method.rs Show resolved Hide resolved
} else {
return Err(HrefError::NotInExternalCache);
return generate_item_def_id_path(did, original_did, cx, root_path);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@notriddle notriddle Feb 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn 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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn 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...

@rustbot 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
Copy link
Member Author

Extended tests and fixed corner cases.

@notriddle
Copy link
Contributor

@bors r+

@bors
Copy link
Contributor

bors commented Feb 7, 2024

📌 Commit 898bb7f has been approved by notriddle

It is now in the queue for this repository.

@bors 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
@GuillaumeGomez
Copy link
Member Author

@bors rollup

matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Feb 7, 2024
…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`
bors added a commit to rust-lang-ci/rust that referenced this pull request Feb 7, 2024
…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
bors added a commit to rust-lang-ci/rust that referenced this pull request Feb 8, 2024
…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
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Feb 8, 2024
…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``
bors added a commit to rust-lang-ci/rust that referenced this pull request Feb 8, 2024
…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
Copy link
Member

@bors r-
#120766 (comment)

@bors 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
Copy link
Member Author

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

@bors r=notriddle

@bors
Copy link
Contributor

bors commented Feb 8, 2024

📌 Commit 11bd2ea has been approved by notriddle

It is now in the queue for this repository.

@bors 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
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Feb 8, 2024
…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`
@bors 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
Copy link
Member Author

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
Copy link
Member Author

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

@bors r=notriddle

@bors
Copy link
Contributor

bors commented Feb 9, 2024

📌 Commit 7940d02 has been approved by notriddle

It is now in the queue for this repository.

@bors 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
@fmease
Copy link
Member

fmease commented Feb 9, 2024

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

@bors 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

// @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'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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'

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


// @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'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto et seqq.

@GuillaumeGomez
Copy link
Member Author

GuillaumeGomez commented Feb 9, 2024

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

@bors r=notriddle,fmease rollup

@bors
Copy link
Contributor

bors commented Feb 9, 2024

📌 Commit 14e0dab has been approved by notriddle,fmease

It is now in the queue for this repository.

@bors 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 added a commit to matthiaskrgr/rust that referenced this pull request Feb 9, 2024
…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`
bors added a commit to rust-lang-ci/rust that referenced this pull request Feb 9, 2024
…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
bors added a commit to rust-lang-ci/rust that referenced this pull request Feb 10, 2024
…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
@bors bors merged commit c06199f into rust-lang:master Feb 10, 2024
11 checks passed
@rustbot rustbot added this to the 1.78.0 milestone Feb 10, 2024
rust-timer added a commit to rust-lang-ci/rust that referenced this pull request Feb 10, 2024
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``
@GuillaumeGomez GuillaumeGomez deleted the jump-to-def-non-local-link branch February 10, 2024 10:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants