From 0fd4c1852f4f1a280c0f377821900a311a6dda2d Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Wed, 28 May 2025 21:20:41 +0100 Subject: [PATCH 1/5] Start documenting tests/rustdoc-json --- src/compiler-src.md | 4 +- .../rustdoc-json-test-suite.md | 46 ++++++++++++++++++- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/src/compiler-src.md b/src/compiler-src.md index d67bacb1b..11b7e15e3 100644 --- a/src/compiler-src.md +++ b/src/compiler-src.md @@ -153,7 +153,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]. @@ -162,6 +163,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 diff --git a/src/rustdoc-internals/rustdoc-json-test-suite.md b/src/rustdoc-internals/rustdoc-json-test-suite.md index e08f77095..79b2ede61 100644 --- a/src/rustdoc-internals/rustdoc-json-test-suite.md +++ b/src/rustdoc-internals/rustdoc-json-test-suite.md @@ -1,3 +1,47 @@ # The `rustdoc-json` test suite -> **FIXME**: This section is a stub. It will be populated by [PR #2422](https://github.com/rust-lang/rustc-dev-guide/pull/2422/). +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. + + + +## jsondocck + + + +### Directives + +- `//@ has `:: Checks `` exists, i.e. matches at least 1 value. +- `//@ !has `:: Checks `` doesn't exist, i.e. matches 0 values. +- `//@ has `: Check `` exists, and 1 of the matches is equal to the given `` +- `//@ !has `: Checks `` exists, but none of the matches equal the given ``. +- `//@ is `: Check `` matches exacly one value, and it's equal to the given ``. +- `//@ is ...`: Check that `` matches to exactly every given ``. + Ordering doesn't matter here. +- `//@ !is `: Check `` matches exactly one value, and that value is not equal to the given ``. +- `//@ count ` Check that `` matches to `` 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 From b5261706855ebce9a597d4b8fde76b6bc1b88a4c Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Sat, 30 Aug 2025 23:50:23 +0100 Subject: [PATCH 2/5] More docs --- src/compiler-src.md | 2 +- .../rustdoc-json-test-suite.md | 48 ++++++++++++++++--- 2 files changed, 43 insertions(+), 7 deletions(-) diff --git a/src/compiler-src.md b/src/compiler-src.md index 11b7e15e3..27b40f1fe 100644 --- a/src/compiler-src.md +++ b/src/compiler-src.md @@ -154,7 +154,7 @@ 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`]. The type definitions for `--output-format=json` -are in a seperate crate in [`src/rustdoc-json-types`]. +are in a separate crate in [`src/rustdoc-json-types`]. You can read more about [`rustdoc`] in [this chapter][rustdoc-chapter]. diff --git a/src/rustdoc-internals/rustdoc-json-test-suite.md b/src/rustdoc-internals/rustdoc-json-test-suite.md index 79b2ede61..efc576cc9 100644 --- a/src/rustdoc-internals/rustdoc-json-test-suite.md +++ b/src/rustdoc-internals/rustdoc-json-test-suite.md @@ -3,19 +3,19 @@ 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). +Tests are run with compiletest, and have access to the usual 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]. +Each crate's json output is checked by 2 programs: [jsondoclint](#jsondocck) and [jsondocck](#jsondocck). ## jsondoclint [jsondoclint] checks that all [`Id`]s exist in the `index` (or `paths`). -This makes sure their are no dangling [`Id`]s. +This makes sure there are no dangling [`Id`]s. +[jsondocck] processes direcives given in comments, to assert that the values in the output are expected. +It's alot like [htmldocck](./rustdoc-test-suite.md) in that way. + +It uses [JSONPath] as a query language, which takes a path, and returns a *list* of values that that path is said to match to. ### Directives - `//@ has `:: Checks `` exists, i.e. matches at least 1 value. - `//@ !has `:: Checks `` doesn't exist, i.e. matches 0 values. -- `//@ has `: Check `` exists, and 1 of the matches is equal to the given `` +- `//@ has `: Check `` exists, and at least 1 of the matches is equal to the given `` - `//@ !has `: Checks `` exists, but none of the matches equal the given ``. -- `//@ is `: Check `` matches exacly one value, and it's equal to the given ``. +- `//@ is `: Check `` matches exactly one value, and it's equal to the given ``. - `//@ is ...`: Check that `` matches to exactly every given ``. Ordering doesn't matter here. - `//@ !is `: Check `` matches exactly one value, and that value is not equal to the given ``. - `//@ count ` Check that `` matches to `` of values. +- `//@ set = `, Check that `` matches exactly one value, and store that value to the variable called `` + +These are defined in [`directive.rs`]. + +### Values + +Values can be either JSON values, or variables. + +- JSON values are JSON literals, e.g. `true`, `"string"`, `{"key": "value"}`. + These often need to be quoted using `'`, to be processed as 1 value. See [§Argument spliting](#argument-spliting) +- Variables can be used to store the value in one path, and use it in later queries. + They are set with the `//@ set = ` directive, and accessed with `$` + + ```rust + //@ set foo = $some.path + //@ is $.some.other.path $foo + ``` + +### Argument spliting + +Arguments to directives are split using the [shlex] crate, which implements POSIX shell escaping. +This is because both `` and `` arguments to [directives](#directives) frequently have both +whitespace and quote marks. + +To use the `@ is` with a `` of `$.index[?(@.docs == "foo")].some.field` and a value of `"bar"` [^why quote], you'd write: +```rust +//@ is '$.is[?(@.docs == "foo")].some.field' '"bar"' +``` +[^why quote]: The value needs to be `"bar"` *after* shlex splitting, because we + it needs to be a JSON string value. [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 @@ -45,3 +78,6 @@ Also, talk about how it works [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 +[`directive.rs`]: https://github.com/rust-lang/rust/blob/master/src/tools/jsondocck/src/directive.rs +[shlex]: https://docs.rs/shlex/1.3.0/shlex/index.html +[JSONPath]: https://www.rfc-editor.org/rfc/rfc9535.html From 940a208a7f8f1d2fb6aefa323f2737f120829bf1 Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Fri, 5 Sep 2025 20:35:51 +0100 Subject: [PATCH 3/5] Make footnote render correctly in github --- src/rustdoc-internals/rustdoc-json-test-suite.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/rustdoc-internals/rustdoc-json-test-suite.md b/src/rustdoc-internals/rustdoc-json-test-suite.md index efc576cc9..2d48878b0 100644 --- a/src/rustdoc-internals/rustdoc-json-test-suite.md +++ b/src/rustdoc-internals/rustdoc-json-test-suite.md @@ -63,13 +63,13 @@ Arguments to directives are split using the [shlex] crate, which implements POSI This is because both `` and `` arguments to [directives](#directives) frequently have both whitespace and quote marks. -To use the `@ is` with a `` of `$.index[?(@.docs == "foo")].some.field` and a value of `"bar"` [^why quote], you'd write: +To use the `@ is` with a `` of `$.index[?(@.docs == "foo")].some.field` and a value of `"bar"` [^why_quote], you'd write: ```rust //@ is '$.is[?(@.docs == "foo")].some.field' '"bar"' ``` -[^why quote]: The value needs to be `"bar"` *after* shlex splitting, because we +[^why_quote]: The value needs to be `"bar"` *after* shlex splitting, because we it needs to be a JSON string value. [json output]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#json-output From 66a095b9ae485ab9459e98c1c79f953ce74c717b Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Fri, 5 Sep 2025 20:39:14 +0100 Subject: [PATCH 4/5] Consistent punctuation --- src/rustdoc-internals/rustdoc-json-test-suite.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/rustdoc-internals/rustdoc-json-test-suite.md b/src/rustdoc-internals/rustdoc-json-test-suite.md index 2d48878b0..3044136c1 100644 --- a/src/rustdoc-internals/rustdoc-json-test-suite.md +++ b/src/rustdoc-internals/rustdoc-json-test-suite.md @@ -30,16 +30,16 @@ It uses [JSONPath] as a query language, which takes a path, and returns a *list* ### Directives -- `//@ has `:: Checks `` exists, i.e. matches at least 1 value. -- `//@ !has `:: Checks `` doesn't exist, i.e. matches 0 values. +- `//@ has `: Checks `` exists, i.e. matches at least 1 value. +- `//@ !has `: Checks `` doesn't exist, i.e. matches 0 values. - `//@ has `: Check `` exists, and at least 1 of the matches is equal to the given `` - `//@ !has `: Checks `` exists, but none of the matches equal the given ``. - `//@ is `: Check `` matches exactly one value, and it's equal to the given ``. - `//@ is ...`: Check that `` matches to exactly every given ``. Ordering doesn't matter here. - `//@ !is `: Check `` matches exactly one value, and that value is not equal to the given ``. -- `//@ count ` Check that `` matches to `` of values. -- `//@ set = `, Check that `` matches exactly one value, and store that value to the variable called `` +- `//@ count `: Check that `` matches to `` of values. +- `//@ set = `: Check that `` matches exactly one value, and store that value to the variable called ``. These are defined in [`directive.rs`]. From 6debd2e882e22e0c3312688c0b372c76f0748e6f Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Fri, 5 Sep 2025 20:41:43 +0100 Subject: [PATCH 5/5] Better link --- src/rustdoc-internals/rustdoc-json-test-suite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/rustdoc-internals/rustdoc-json-test-suite.md b/src/rustdoc-internals/rustdoc-json-test-suite.md index 3044136c1..10e9452ed 100644 --- a/src/rustdoc-internals/rustdoc-json-test-suite.md +++ b/src/rustdoc-internals/rustdoc-json-test-suite.md @@ -1,7 +1,7 @@ # 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). +For other test suites used for testing rustdoc, see [§Rustdoc test suites](../tests/compiletest.md#rustdoc-test-suites). Tests are run with compiletest, and have access to the usual set of [directives](../tests/directives.md). Frequenly used directives here are: