Rustdoc Json Cross Crate Resolution (rdxcr)

NOTE: This is heavily work in progress. It's not robust, and has known edge-cases.

An experimental crate to do cross-crate resolution for rustdoc json.

Rustdoc json output for a crate, (rustdoc_types::Crate, henceforth Crate) only has items for that crate. But many times, you want to find information about the items in another crate. This library is designed to help you do that.

Ambitions & Status

Eventually, I'd like this to be a robust library that tools like cargo-semver-checks and pavex can depend on.

Currently, it's an experiment, to see if it's possible to use ExternalCrate::path and rust#149043, and how.

Contributions welcome! Discussions can happen in the t-rustdoc channel of the rust zulip [^offical].

[offical]: Note: This library isn't an offical part of the rust project, but something I'm doing in a personal capacity. But figuring out how to use new capibilites in rustdoc, and if rustdoc needs changes is on-topic there.

TODO

Fundamental correctness:

• Resolve cargo#16291, to fix cacheing issue.

  • Probably also involves rust#142370

• Resolve enabling optional features in dependencies. See ./tests/conditionally_enable_features.rs.

  $ cargo rustdoc -p dep --features=a
  error: cannot specify features for packages outside of workspace
  

  Possible solution: Run cargo doc -- --output-format=rustdoc so that cargo builds all rdj outputs, rather that 1 at a time.

  This has many downsides:

  1. In means we now need to invoke rustdoc on all crates, not just the crates we care about.
  2. RUSTDOCFLAGS="-Zunstable-options -wjson" cargo doc --message-format json is broken cargo#15558.
  3. Would require fixing rust#142370.

  The #2 and #3 we should do anyway. #1 is very sad.

  Alternative solution: Change cargo to allow specify features for other packages. I have much less idea what this would involve. But I'd at least like to know the chesterton's fence about why things are this way.

Tidying:

• Is it ok to require camino::Utf8Path?
• Better error handling
• Cacheing.
• Multiple rustdoc-json formats?
• Allow caller to control how cargo is spawned
• How to handle rustup distributes .rlibs
• Clone less?
• Should there be an api to resolve from a ExternalCrate rather than a crate_id?

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in rdxcr by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.