Historically, it's not been possible to robustly resolve a cross-crate
item in rustdoc-json. If you had a `Id` that wasn't in `Crate::index`
(because it was defined in a different crate), you could only look it up
it `Crate::paths`. But there, you don't get the full information, only
an `ItemSummary`. This tells you the `path` and the `crate_id`.
But knowing the `crate_id` isn't enough to be able to build/find the
rustdoc-json output with this item. It's only use is to get a
`ExternalCrate` (via `Crate::external_crates`). But that only tells you
the `name` (as a string). This isn't enough to uniquely identify a
crate, as there could be multiple versions/features [1] [2].
This was originally proposed to be solved via LukeMathWalker's
`--orchestrator-id` proposal
(https://www.github.com/rust-lang/compiler-team/issues/635). But that
requires invasive changes to cargo/rustc. This PR instead implements
Urgau's proposal to re-use the path to a crate's rmeta/rlib as a unique
identifer. Callers can use that to determine which package it
corresponds to in the language of the build-system above rustc. E.g. for
cargo, `cargo rustdoc --message-format=json --output-format=json
-Zunstable-options`).
(Once you've found the right external crate's rustdoc-json output, you
still need to resolve the path->id in that crate. But that's """just"""
a matter of walking the module tree. We should probably still make that
nicer (by, for example, allowing sharing `Id`s between rustdoc-json
document), but that's a future concern)
For some notes from RustWeek 2025, where this was designed, see
https://hackmd.io/0jkdguobTnW7nXoGKAxfEQ
[1]: https://www.github.com/rust-lang/compiler-team/issues/635#issue-1714254865 § Problem
[2]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/Identifying.20external.20crates.20in.20Rustdoc.20JSON/with/352701211
361af821ab