Start documenting tests/rustdoc-json

src/SUMMARY.md

@@ -101,6 +101,7 @@
 - [Rustdoc internals](./rustdoc-internals.md)
     - [Search](./rustdoc-internals/search.md)
 	- [The `rustdoc` test suite](./rustdoc-internals/rustdoc-test-suite.md)
+    - [The `rustdoc-json` test suite](./rustdoc-internals/rustdoc-json-test-suite.md)
 - [Autodiff internals](./autodiff/internals.md)
     - [Installation](./autodiff/installation.md)
     - [How to debug](./autodiff/debugging.md)

src/compiler-src.md

@@ -155,7 +155,8 @@ The bulk of [`rustdoc`] is in [`librustdoc`]. However, the [`rustdoc`] binary
 itself is [`src/tools/rustdoc`], which does nothing except call [`rustdoc::main`].
 
 There is also `JavaScript` and `CSS` for the docs in [`src/tools/rustdoc-js`]
-and [`src/tools/rustdoc-themes`].
+and [`src/tools/rustdoc-themes`]. The type definitions for `--output-format=json`
+are in a seperate crate in [`src/rustdoc-json-types`].
 
 You can read more about [`rustdoc`] in [this chapter][rustdoc-chapter].
 
@@ -164,6 +165,7 @@ You can read more about [`rustdoc`] in [this chapter][rustdoc-chapter].
 [`src/tools/rustdoc-js`]: https://github.com/rust-lang/rust/tree/master/src/tools/rustdoc-js
 [`src/tools/rustdoc-themes`]: https://github.com/rust-lang/rust/tree/master/src/tools/rustdoc-themes
 [`src/tools/rustdoc`]:  https://github.com/rust-lang/rust/tree/master/src/tools/rustdoc
+[`src/rustdoc-json-types`]: https://github.com/rust-lang/rust/tree/master/src/rustdoc-json-types
 [rustdoc-chapter]: ./rustdoc.md
 
 ## Tests

src/rustdoc-internals.md

@@ -214,7 +214,7 @@ directly, even during `HTML` generation. This [didn't used to be the case], and
 a lot of `rustdoc`'s architecture was designed around not doing that, but a
 `TyCtxt` is now passed to `formats::renderer::run_format`, which is used to
 run generation for both `HTML` and the
-(unstable as of <!-- date-check --> March 2023) JSON format.
+(unstable as of <!-- date-check --> May 2025) JSON format.
 
 This change has allowed other changes to remove data from the "clean" [`AST`][ast]
 that can be easily derived from `TyCtxt` queries, and we'll usually accept

src/rustdoc-internals/rustdoc-json-test-suite.md

@@ -0,0 +1,47 @@
+# The `rustdoc-json` test suite
+
+This page is specifically about the test suite named `rustdoc-json`, which tests rustdoc's [json output].
+For other test suites used for testing rustdoc, see [Rustdoc tests](../rustdoc.md#tests).
+
+Tests are run with compiletest, and have access to the usuall set of [directives](../tests/directives.md).
+Frequenly used directives here are:
+
+- [`//@ aux-build`][aux-build] to have dependencies.
+- `//@ edition: 2021` (or some other edition).
+- `//@ compile-flags: --document-hidden-items` to enable [document private items].
+
+Each crate's json output is checked by 2 programs: [jsondoclint] and [jsondocck].
+
+## jsondoclint
+
+[jsondoclint] checks that all [`Id`]s exist in the `index` (or `paths`).
+This makes sure their are no dangling [`Id`]s.
+
+<!-- TODO: It does some more things too?
+Also, talk about how it works
+ -->
+
+## jsondocck
+
+<!-- TODO: shlex, jsonpath, values, variables -->
+
+### Directives
+
+- `//@ has <path>`:: Checks `<path>` exists, i.e. matches at least 1 value.
+- `//@ !has <path>`:: Checks `<path>` doesn't exist, i.e. matches 0 values.
+- `//@ has <path> <value>`: Check `<path>` exists, and 1 of the matches is equal to the given `<value>` 
+- `//@ !has <path> <value>`: Checks `<path>` exists, but none of the matches equal the given `<value>`.
+- `//@ is <path> <value>`: Check `<path>` matches exacly one value, and it's equal to the given `<value>`.
+- `//@ is <path> <value> <value>...`: Check that `<path>` matches to exactly every given `<value>`. 
+   Ordering doesn't matter here.
+- `//@ !is <path> <value>`: Check `<path>` matches exactly one value, and that value is not equal to the given `<value>`.
+- `//@ count <path> <number>` Check that `<path>` matches to `<number>` of values.
+
+
+
+[json output]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#json-output
+[jsondocck]: https://github.com/rust-lang/rust/tree/master/src/tools/jsondocck
+[jsondoclint]: https://github.com/rust-lang/rust/tree/master/src/tools/jsondoclint
+[aux-build]: ../tests/compiletest.md#building-auxiliary-crates
+[`Id`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/struct.Id.html
+[document private items]: https://doc.rust-lang.org/nightly/rustdoc/command-line-arguments.html#--document-private-items-show-items-that-are-not-public