rustdoc-json: multiple package versions clobber their output paths
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
Rustdoc uses crate name as a base for file names (target/doc/$name.json), but this naming scheme is incompatible with Cargo projects where names are not unique, and multiple different crates can have the same name.
[package]
name = "exampledoc" # try `name = "wild"` for extra difficulty
edition = "2024"
[dependencies]
old = { package = "wild", version = "1" }
new = { package = "wild", version = "2" }
pub use ::old;
pub use ::new;
RUSTDOCFLAGS="-Z unstable-options --output-format=json" cargo +nightly doc
This ends up writing target/doc/wild.json for only one of the two versions. The same problem can happen if Cargo has git, path, or custom registry dependencies that use names overlapping with crates-io dependencies, so even name + version isn't unique.
Using the package alias (new and old in this example) wouldn't be sufficient, because these aliases aren't globally unique either. Different crates in the same dependency tree can rename different deps to the same name.
cargo 1.89.0-nightly (fc1518ef0 2025-06-06)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the collision with the provided Cargo project and RUSTDOCFLAGS command, then trace rustdoc JSON output-path handling from the generated target/doc files. Investigate how dependency identity is represented for crates.io, git, path, and custom registry dependencies; done means distinct outputs are produced without clobbering when package names overlap.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100