search

rust-lang / rustdoc-types

Rustdoc's JSON output interface
Apache License 2.0
28 stars 15 forks source link

Lenient deserialization of all previous `FORMAT_VERSION`s #37

Closed Boscop closed 2 weeks ago

Boscop commented 2 weeks ago

I was using the latest version of this crate to generate JSON rustdoc output, but there was a version mismatch with the format that rustdoc executable generated: https://docs.rs/rustdoc-types/0.29.1/rustdoc_types/struct.Header.html vs https://docs.rs/rustdoc-types/0.30.0/rustdoc_types/struct.FunctionHeader.html because the workspace that I wanted to document was using an older nightly.

Is there a way to be able to deserialize ALL previous formats in the same executable that uses rustdoc-types? Because I intend to distribute my executable / use the compiled executable on different machines, but if it invokes the rustdoc executable that's installed for the user, it might use a different FORMAT_VERSION. And every workspace might be pinned to a different Rust nightly, so currently it requires source code modification every time I want to accommodate a different nightly in the workspace that I want to run it on :/

Even better: Is there a way to invoke not the rustdoc executable but link to the crate so that the versions always match? 🙂

aDotInTheVoid commented 2 weeks ago

Is there a way to be able to deserialize ALL previous formats in the same executable that uses rustdoc-types?

If you depend on every single version of rustdoc-types! (although we somehow don't have releases corresponding to some extremely old format versions (3, 4, 7), and I don't think this is worth fixing). You'll then need to write code such that it can handle multiple different types. This is do-able, but is a lot of investment.

Is there a way to invoke not the rustdoc executable but link to the crate so that the versions always match? 🙂

No, the only real interface into rustdoc is via the CLI. You could in theory link into librustdoc via #![feature(rustc_private)], but that's extreamly painful (as the API isn't set up at all for external use). It also doesn't solve your problems:

  1. You now need to build with the same version from rustc/rustdoc you linked, so the problem of unsupported nightly versions is still there for you.
  2. rustdoc dynamically links to librustc_driver and libLLVM, so the user still needs to have that version installed.
Boscop commented 1 week ago

Ah.. But I can only depend on one version of a crate, unless I make a new wrapper crate for each version, right?

Which solution do you recommend? I just need support for the most recent format versions (like always covering the last year or so).

aDotInTheVoid commented 1 week ago

But I can only depend on one version of a crate, unless I make a new wrapper crate for each version, right?

Nope!

Which solution do you recommend?

Personally, latest nightly only.