rustc-dev-guide subtree update

src/doc/rustc-dev-guide/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     if: github.repository == 'rust-lang/rustc-dev-guide'
     runs-on: ubuntu-latest
     env:
-      MDBOOK_VERSION: 0.4.48
+      MDBOOK_VERSION: 0.4.52
       MDBOOK_LINKCHECK2_VERSION: 0.9.1
       MDBOOK_MERMAID_VERSION: 0.12.6
       MDBOOK_OUTPUT__LINKCHECK__FOLLOW_WEB_LINKS: ${{ github.event_name != 'pull_request' }}

src/doc/rustc-dev-guide/rust-version

@@ -1 +1 @@
-a1dbb443527bd126452875eb5d5860c1d001d761
+2f3f27bf79ec147fec9d2e7980605307a74067f4

src/doc/rustc-dev-guide/src/about-this-guide.md

@@ -73,7 +73,7 @@ You might also find the following sites useful:
 - [compiler-team] -- the home-base for the Rust compiler team, with description
   of the team procedures, active working groups, and the team calendar.
 - [std-dev-guide] -- a similar guide for developing the standard library.
-- [The t-compiler zulip][z]
+- [The t-compiler Zulip][z]
 - The [Rust Internals forum][rif], a place to ask questions and
   discuss Rust's internals
 - The [Rust reference][rr], even though it doesn't specifically talk about

src/doc/rustc-dev-guide/src/appendix/code-index.md

@@ -13,7 +13,7 @@ Item            |  Kind    | Short description           | Chapter            |
 `DefId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [compiler/rustc_hir/src/def_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html)
 `Diag` | struct | A struct for a compiler diagnostic, such as an error or lint | [Emitting Diagnostics] | [compiler/rustc_errors/src/diagnostic.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Diag.html)
 `DocContext` | struct | A state container used by rustdoc when crawling through a crate to gather its documentation | [Rustdoc] | [src/librustdoc/core.rs](https://github.com/rust-lang/rust/blob/master/src/librustdoc/core.rs)
-`HirId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [compiler/rustc_hir/src/hir_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir_id/struct.HirId.html)
+`HirId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [compiler/rustc_hir_id/src/lib.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.HirId.html)
 `Lexer` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] |  [compiler/rustc_parse/src/lexer/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/lexer/struct.Lexer.html)
 `NodeId` | struct | One of four types of HIR node identifiers. Being phased out | [Identifiers in the HIR] | [compiler/rustc_ast/src/ast.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/node_id/struct.NodeId.html)
 `P` | struct | An owned immutable smart pointer. By contrast, `&T` is not owned, and `Box<T>` is not immutable. | None | [compiler/rustc_ast/src/ptr.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ptr/struct.P.html)

src/doc/rustc-dev-guide/src/backend/debugging.md

@@ -183,7 +183,7 @@ The quick summary is:
 ### Getting help and asking questions
 
 If you have some questions, head over to the [rust-lang Zulip] and
-specifically the `#t-compiler/wg-llvm` stream.
+specifically the `#t-compiler/wg-llvm` channel.
 
 [rust-lang Zulip]: https://rust-lang.zulipchat.com/
 

src/doc/rustc-dev-guide/src/compiler-debugging.md

@@ -367,7 +367,7 @@ error: layout_of(&'a u32) = Layout {
 error: aborting due to previous error
 ```
 
-[`Layout`]: https://doc.rust-lang.org/nightly/nightly-rustc/stable_mir/abi/struct.Layout.html
+[`Layout`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_public/abi/struct.Layout.html
 
 
 ## Configuring CodeLLDB for debugging `rustc`

src/doc/rustc-dev-guide/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 separate 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

src/doc/rustc-dev-guide/src/compiler-team.md

@@ -12,7 +12,7 @@ contributions to rustc and its design.
 Currently the compiler team chats in Zulip:
 
 - Team chat occurs in the [`t-compiler`][zulip-t-compiler] stream on the Zulip instance
-- There are also a number of other associated Zulip streams,
+- There are also a number of other associated Zulip channels,
   such as [`t-compiler/help`][zulip-help], where people can ask for help
   with rustc development, or [`t-compiler/meetings`][zulip-meetings],
   where the team holds their weekly triage and steering meetings.

src/doc/rustc-dev-guide/src/contributing.md

@@ -26,8 +26,7 @@ conditions that trigger the bug, or part of the error message if there is any.
 An example could be: **"impossible case reached" on lifetime inference for impl
 Trait in return position**.
 
-Opening an issue is as easy as following [this
-link](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields
+Opening an issue is as easy as following [thi link][create an issue] and filling out the fields
 in the appropriate provided template.
 
 ## Bug fixes or "normal" code changes
@@ -75,7 +74,7 @@ Example of things that might require MCPs include major refactorings, changes
 to important types, or important changes to how the compiler does something, or
 smaller user-facing changes.
 
-**When in doubt, ask on [zulip]. It would be a shame to put a lot of work
+**When in doubt, ask on [Zulip]. It would be a shame to put a lot of work
 into a PR that ends up not getting merged!** [See this document][mcpinfo] for
 more info on MCPs.
 
@@ -127,7 +126,7 @@ when contributing to Rust under [the git section](./git.md).
 > from), and work with the compiler team to see if we can help you **break down a large potentially
 > unreviewable PR into a series of smaller more individually reviewable PRs**.
 >
-> You can communicate with the compiler team by creating a [#t-compiler thread on zulip][t-compiler]
+> You can communicate with the compiler team by creating a [#t-compiler thread on Zulip][t-compiler]
 > to discuss your proposed changes.
 >
 > Communicating with the compiler team beforehand helps in several ways:
@@ -154,11 +153,14 @@ The CI in rust-lang/rust applies your patches directly against the current maste
 not against the commit your branch is based on. This can lead to unexpected failures
 if your branch is outdated, even when there are no explicit merge conflicts.
 
-Before submitting or updating a PR, make sure to update your branch
-as mentioned [here](git.md#keeping-things-up-to-date) if it's significantly
-behind the master branch (e.g., more than 100 commits behind).
-This fetches the latest master branch and rebases your changes on top of it,
-ensuring your PR is tested against the latest code.
+Update your branch only when needed: when you have merge conflicts, upstream CI is broken and blocking your green PR, or a maintainer requests it.
+Avoid updating an already-green PR under review unless necessary.
+During review, make incremental commits to address feedback.
+Prefer to squash or rebase only at the end, or when a reviewer requests it.
+
+When updating, use `git push --force-with-lease` and leave a brief comment explaining what changed.
+Some repos prefer merging from `upstream/master` instead of rebasing; follow the project's conventions.
+See [keeping things up to date](git.md#keeping-things-up-to-date) for detailed instructions.
 
 After rebasing, it's recommended to [run the relevant tests locally](tests/intro.md) to catch any issues before CI runs.
 
@@ -372,6 +374,11 @@ You can also use `rustdoc` directly to check small fixes. For example,
 `rustdoc src/doc/reference.md` will render reference to `doc/reference.html`.
 The CSS might be messed up, but you can verify that the HTML is right.
 
+Please notice that we don't accept typography/spellcheck fixes to **internal documentation**
+as it's usually not worth the churn or the review time.
+Examples of internal documentation is code comments and rustc api docs.
+However, feel free to fix those if accompanied by other improvements in the same PR.
+
 ### Contributing to rustc-dev-guide
 
 Contributions to the [rustc-dev-guide] are always welcome, and can be made directly at
@@ -434,7 +441,8 @@ Just a few things to keep in mind:
 
 #### ⚠️ Note: Where to contribute `rustc-dev-guide` changes
 
-For detailed information about where to contribute rustc-dev-guide changes and the benefits of doing so, see [the rustc-dev-guide working group documentation](https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes).
+For detailed information about where to contribute rustc-dev-guide changes and the benefits of doing so,
+see [the rustc-dev-guide working group documentation].
 
 ## Issue triage
 
@@ -451,6 +459,7 @@ Please see <https://forge.rust-lang.org/release/issue-triaging.html>.
 [regression-]: https://github.com/rust-lang/rust/labels?q=regression
 [relnotes]: https://github.com/rust-lang/rust/labels/relnotes
 [S-tracking-]: https://github.com/rust-lang/rust/labels?q=s-tracking
+[the rustc-dev-guide working group documentation]: https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes
 
 ### Rfcbot labels
 
@@ -498,3 +507,4 @@ This section has moved to the ["About this guide"] chapter.
 [RFC 1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
 [rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/
 [rdgrepo]: https://github.com/rust-lang/rustc-dev-guide
+[create an issue]: https://github.com/rust-lang/rust/issues/new/choose

src/doc/rustc-dev-guide/src/hir.md

@@ -102,7 +102,7 @@ These identifiers can be converted into one another through the `TyCtxt`.
 
 [`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html
 [`LocalDefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.LocalDefId.html
-[`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir_id/struct.HirId.html
+[`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.HirId.html
 [`BodyId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/struct.BodyId.html
 [Node]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/enum.Node.html
 [`CrateNum`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.CrateNum.html

src/doc/rustc-dev-guide/src/notification-groups/arm.md

@@ -9,7 +9,7 @@ This list will be used to ask for help both in diagnosing and testing
 ARM-related issues as well as suggestions on how to resolve
 interesting questions regarding our ARM support.
 
-The group also has an associated Zulip stream ([`#t-compiler/arm`])
+The group also has an associated Zulip channel ([`#t-compiler/arm`])
 where people can go to pose questions and discuss ARM-specific
 topics.
 

src/doc/rustc-dev-guide/src/notification-groups/emscripten.md

@@ -9,7 +9,7 @@ This list will be used to ask for help both in diagnosing and testing
 Emscripten-related issues as well as suggestions on how to resolve
 interesting questions regarding our Emscripten support.
 
-The group also has an associated Zulip stream ([`#t-compiler/wasm`])
+The group also has an associated Zulip channel ([`#t-compiler/wasm`])
 where people can go to pose questions and discuss Emscripten-specific
 topics.
 

src/doc/rustc-dev-guide/src/notification-groups/risc-v.md

@@ -9,7 +9,7 @@ This list will be used to ask for help both in diagnosing and testing
 RISC-V-related issues as well as suggestions on how to resolve
 interesting questions regarding our RISC-V support.
 
-The group also has an associated Zulip stream ([`#t-compiler/risc-v`])
+The group also has an associated Zulip channel ([`#t-compiler/risc-v`])
 where people can go to pose questions and discuss RISC-V-specific
 topics.
 

src/doc/rustc-dev-guide/src/notification-groups/rust-for-linux.md

@@ -12,7 +12,7 @@ and features. The RfL maintainers should then ideally provide support
 for resolving the breakage or decide to temporarily accept the breakage
 and unblock CI by temporarily removing the RfL CI jobs.
 
-The group also has an associated Zulip stream ([`#rust-for-linux`])
+The group also has an associated Zulip channel ([`#rust-for-linux`])
 where people can go to ask questions and discuss topics related to Rust
 for Linux.
 

src/doc/rustc-dev-guide/src/notification-groups/wasi.md

@@ -9,7 +9,7 @@ This list will be used to ask for help both in diagnosing and testing
 WASI-related issues as well as suggestions on how to resolve
 interesting questions regarding our WASI support.
 
-The group also has an associated Zulip stream ([`#t-compiler/wasm`])
+The group also has an associated Zulip channel ([`#t-compiler/wasm`])
 where people can go to pose questions and discuss WASI-specific
 topics.
 

src/doc/rustc-dev-guide/src/notification-groups/wasm.md

@@ -9,7 +9,7 @@ This list will be used to ask for help both in diagnosing and testing
 WebAssembly-related issues as well as suggestions on how to resolve
 interesting questions regarding our WASM support.
 
-The group also has an associated Zulip stream ([`#t-compiler/wasm`])
+The group also has an associated Zulip channel ([`#t-compiler/wasm`])
 where people can go to pose questions and discuss WASM-specific
 topics.
 

src/doc/rustc-dev-guide/src/notification-groups/windows.md

@@ -9,7 +9,7 @@ This list will be used to ask for help both in diagnosing and testing
 Windows-related issues as well as suggestions on how to resolve
 interesting questions regarding our Windows support.
 
-The group also has an associated Zulip stream ([`#t-compiler/windows`])
+The group also has an associated Zulip channel ([`#t-compiler/windows`])
 where people can go to pose questions and discuss Windows-specific
 topics.
 

src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-json-test-suite.md

@@ -1,3 +1,83 @@
 # 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 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:
+
+- [`//@ 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](#jsondocck) and [jsondocck](#jsondocck).
+
+## jsondoclint
+
+[jsondoclint] checks that all [`Id`]s exist in the `index` (or `paths`).
+This makes sure there are no dangling [`Id`]s.
+
+<!-- TODO: It does some more things too?
+Also, talk about how it works
+ -->
+
+## jsondocck
+
+[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 <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 at least 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 exactly 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.
+- `//@ set <name> = <path>`: Check that `<path>` matches exactly one value, and store that value to the variable called `<name>`.
+
+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 <name> = <path>` directive, and accessed with `$<name>`
+
+  ```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 `<path>` and `<value>` arguments to [directives](#directives) frequently have both
+whitespace and quote marks.
+
+To use the `@ is` with a `<path>` 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
+[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
+[`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

src/doc/rustc-dev-guide/src/rustdoc.md

@@ -107,7 +107,7 @@ This comes with several caveats: in particular, rustdoc *cannot* run any parts o
 require type-checking bodies; for example it cannot generate `.rlib` files or run most lints.
 We want to move away from this model eventually, but we need some alternative for
 [the people using it][async-std]; see [various][zulip stop accepting broken code]
-[previous][rustdoc meeting 2024-07-08] [zulip][compiler meeting 2023-01-26] [discussion][notriddle rfc].
+[previous][rustdoc meeting 2024-07-08] [Zulip][compiler meeting 2023-01-26] [discussion][notriddle rfc].
 For examples of code that breaks if this hack is removed, see
 [`tests/rustdoc-ui/error-in-impl-trait`].
 

src/doc/rustc-dev-guide/src/serialization.md

@@ -106,7 +106,7 @@ type wrapper, like [`ty::Predicate`] and manually implementing `Encodable` and
 [`Encodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encodable.html
 [`Encoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encoder.html
 [`RefDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.RefDecodable.html
-[`rustc_middle`]: https://doc.rust-lang.org/nightly/nightly-rustc/src/rustc_type_ir/codec.rs.html#21
+[`rustc_middle`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/index.html
 [`ty::Predicate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/predicate/struct.Predicate.html
 [`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html
 [`TyDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_macros/derive.TyDecodable.html