361af821ab
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 |
||
|---|---|---|
| .. | ||
| Cargo.toml | ||
| lib.rs | ||
| README.md | ||
| tests.rs | ||
Rustdoc JSON Types
This crate exposes the Rustdoc JSON API as a set of types with serde implementations. These types are part of the public interface of the rustdoc JSON output, and making them their own crate allows them to be versioned and distributed without having to depend on any rustc/rustdoc internals. This way, consumers can rely on this crate for both documentation of the output, and as a way to read the output easily, and its versioning is intended to follow semver guarantees about the version of the format. JSON format X will always be compatible with rustdoc-json-types version N.
Currently, this crate is only used by rustdoc itself. Upon the stabilization of rustdoc-json, it may be distributed separately for consumers of the API.