Split rustdoc JSON types into separately versioned crate

[CraftSpider]

For now just an in-tree change.

In the future, this may be exposed as a standalone crate with standard semver.

[rust-highfive]

r? @GuillaumeGomez

(rust-highfive has picked a reviewer for you, use r? to override)

[CraftSpider]

r? @jyn514
I'll remember to put this in the original post someday

[rust-log-analyzer]

The job x86_64-gnu-llvm-9 failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

##########################################################                81.2%
######################################################################## 100.0%
extracting /checkout/obj/build/cache/2020-11-19/rustfmt-nightly-x86_64-unknown-linux-gnu.tar.xz
    Updating crates.io index
error: the lock file /checkout/Cargo.lock needs to be updated but --locked was passed to prevent this
If you want to try to generate the lock file without accessing the network, use the --offline flag.
Build completed unsuccessfully in 0:00:39
make: *** [prepare] Error 1
Makefile:60: recipe for target 'prepare' failed
Command failed. Attempt 2/5:
Command failed. Attempt 2/5:
error: the lock file /checkout/Cargo.lock needs to be updated but --locked was passed to prevent this
If you want to try to generate the lock file without accessing the network, use the --offline flag.
Build completed unsuccessfully in 0:00:00
make: *** [prepare] Error 1
Makefile:60: recipe for target 'prepare' failed
Command failed. Attempt 3/5:
Command failed. Attempt 3/5:
error: the lock file /checkout/Cargo.lock needs to be updated but --locked was passed to prevent this
If you want to try to generate the lock file without accessing the network, use the --offline flag.
Build completed unsuccessfully in 0:00:00
make: *** [prepare] Error 1
Makefile:60: recipe for target 'prepare' failed
Command failed. Attempt 4/5:
Command failed. Attempt 4/5:
error: the lock file /checkout/Cargo.lock needs to be updated but --locked was passed to prevent this
If you want to try to generate the lock file without accessing the network, use the --offline flag.
Build completed unsuccessfully in 0:00:00
make: *** [prepare] Error 1
Makefile:60: recipe for target 'prepare' failed
Command failed. Attempt 5/5:
Command failed. Attempt 5/5:
error: the lock file /checkout/Cargo.lock needs to be updated but --locked was passed to prevent this
If you want to try to generate the lock file without accessing the network, use the --offline flag.
Build completed unsuccessfully in 0:00:00
make: *** [prepare] Error 1
Makefile:60: recipe for target 'prepare' failed
The command has failed after 5 attempts.

[rust-log-analyzer]

The job mingw-check failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

    Checking tempfile v3.1.0
    Checking regex v1.4.3
    Checking json-types v0.1.0 (/checkout/src/librustdoc/json-types)
    Checking rustdoc v0.0.0 (/checkout/src/librustdoc)
error: Prefer FxHashMap over HashMap, it has better performance
   --> src/librustdoc/json/mod.rs:219:35
    |
219 |                 std::collections::HashMap::with_capacity(len),
    |                                   ^^^^^^^ help: use: `FxHashMap`
note: the lint level is defined here
   --> src/librustdoc/lib.rs:21:9
    |
    |
21  | #![deny(rustc::internal)]
    |         ^^^^^^^^^^^^^^^
    = note: `#[deny(rustc::default_hash_types)]` implied by `#[deny(rustc::internal)]`
    = note: a `use rustc_data_structures::fx::FxHashMap` may be necessary
error: aborting due to previous error

error: could not compile `rustdoc`

[GuillaumeGomez]

Could you provide more information about this please? Why making it a standalone library would be better for example?

[CraftSpider]

See this conversation for the details: https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/JSON.20Format/near/223685843
Basically, these types are part of the public interface of the rustdoc JSON output. Making them their own crate allows them to be versioned and distributed without having to depend on any rustdoc internals. This way, consumers can rely on this crate for both documentation of the output, and as a way to read the output easily, and its versioning is intended to follow semver guarantees about the version of the format. So JSON format X will always be compatible with json-types version N.

[GuillaumeGomez]

Ok I see, makes sense. However, could you move this library outside of src/librustdoc please? In src/json-types directly would be fine I guess.

[CraftSpider]

@jyn514 advised me to put it in librustdoc, so I'd like to give him a chance to comment first. If he agrees, I'll move it.

[GuillaumeGomez]

You're right, let's maybe talk about it before you make any further changes. ;)

[jyn514]

I would prefer to keep this in librustdoc. It will only be used by rustdoc (src/json-types? types of what?) and I think having the Cargo.toml will make it clear that it's a separate crate.

[GuillaumeGomez]

I disagree. We have split all sub-crates and put them in their own folders for the compiler, so I think we should do the same here since the end goal is to put it out of tree. If the src location doesn't look good to you, another folder sounds good to me. Just not the same as librustdoc.

[jyn514]

Ok, then src/etc/json-types seems reasonable to me. But I don't think it should be at the top-level.

[GuillaumeGomez]

Sounds good to me!

[CraftSpider]

Alright, if src/etc/json-types is agreed on, I'll do the move

[jyn514]

r=me with the directory renamed to src/etc/json-types.

[Mark-Simulacrum]

etc seems like a really bad place. I'm worried we might be blanket copying that directory for dist too somewhere. Can we do src/rustdoc-json-types?

[CraftSpider]

Moved the crate, and updated all the relevant files

[jyn514]

@bors r+

[bors]

📌 Commit 36284a3 has been approved by jyn514

[bors]

☔ The latest upstream changes (presumably #80987) made this pull request unmergeable. Please resolve the merge conflicts.

[CraftSpider]

Merge conflict fixed, checks are green

[GuillaumeGomez]

Thanks!

@bors r=jyn514,GuillaumeGomez squash

[bors]

📌 Commit 3aa8456 has been approved by jyn514,GuillaumeGomez

[aDotInTheVoid]

@rustbot modify labels: +A-rustdoc-json