rdxcr 0.0.1

Rustdoc Json Cross-Crate Resolution
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# 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](./tests/conditionally_enable_feature.rs).

    ```console
    $ 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](LICENSE-APACHE) or [MIT license](LICENSE-MIT) 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.

[rust zulip]: https://rust-lang.zulipchat.com/

[cargo-semver-checks]: https://github.com/obi1kenobi/cargo-semver-checks/
[pavex]: https://github.com/LukeMathWalker/pavex/
[`ExternalCrate::path`]: https://docs.rs/rustdoc-types/0.57.0/rustdoc_types/struct.ExternalCrate.html#structfield.path

[rust#142370]: https://github.com/rust-lang/rust/issues/142370
[rust#149043]: https://github.com/rust-lang/rust/pull/149043/
[cargo#15558]: https://github.com/rust-lang/cargo/issues/15558
[cargo#16291]: https://github.com/rust-lang/cargo/issues/16291