Allow rustdoc JSON rustup component to be installed on stable.

[obi1kenobi]

Currently, the rust-docs-json component is only available on nightly Rust.

It would be very useful to cargo-semver-checks to have rustdoc JSON available in stable as well, to allow performing cross-crate linting that involves types from std/core/alloc etc. This will also simplify the process of linting the standard library itself for possible breaking changes, which is something T-libs is interested in as well.

Even though rustdoc JSON is an unstable component, each JSON file carries a version number meaning that the installed files remain parseable and usable with the matching version of rustdoc-types. So even though future stable Rust releases may change the format, it still makes sense to provide this machine-readable artifact that says "this is what the standard lib contained in this stable release."

For avoidance of confusion: different stable releases may ship mutually-incompatible rustdoc format versions in the rust-docs-json component. The component's contents and shape are valid with respect only to the toolchain in which it is found, analogously to how the rustdoc HTML docs component works.

Zulip Discussion

r? @Mark-Simulacrum @GuillaumeGomez

[obi1kenobi]

@rustbot label +T-rustdoc +A-rustdoc-json

[obi1kenobi]

@rustbot label -T-rustdoc

thanks Urgau! I misspelled the rustdoc JSON team label 🙈

[GuillaumeGomez]

Just to confirm the rustdoc JSON team is onboard:

@rfcbot fcp merge T-rustdoc-json-backend

[rust-rfcbot]

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Urgau
• @aDotInTheVoid

Concerns:

• no-disclaimer-in-json (Allow rustdoc JSON rustup component to be installed on stable. #156926 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[Urgau]

I'm not sure about doing this, exposing artifacts of an unstable (nightly-only) feature doesn't seems very useful, but I can concede that it might be useful in some circumstances.

(I do think we should try to stabilize the output soon-ish)

---

I do have a of concern I would like to get resolve before we expose it on stable.

We currently don't have any kind of warning in the json about the unstable-ness of the format, which is fine for a nightly-only but I think the distributed JSON (and all json produced for that matter) should include (at the top) a disclaimer.

Something like this (following .cargo-checksum.json):

{
   "$comment": "The format of this file is unstable and subject to change without notice, please always follow `format_version`.",
   // ...
}

@rfcbot concern no-disclaimer-in-json

[obi1kenobi]

I'm having a bit of trouble properly interpreting the "not that useful" comment, so just making sure I understand — is your suggestion @Urgau to add a disclaimer to the JSON and then allow the prebuilt std/core/alloc rustdoc JSON component to be installable on stable?

Or is the suggestion to first add a disclaimer, then stabilize the format itself, and then make the prebuilt stdlib rustdoc JSON component installable on stable?

If it's the former, I'm happy to open a PR to do that right away. If it's the latter, I have strong reservations.

[Urgau]

Ideally we would stabilize --output-format json first (not the format, it would remain unstable), but I guess we add the disclaimer it's fine to distribute the JSON on stable.