From 4931cf6ae7d1700acfd15adbf9ac830b3355afd3 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:12:01 -0800 Subject: [PATCH 01/39] Start a contributor guide This is the beginning of a new mdbook book that will house all of the guidelines for contributors. This is published via GitHub Pages. --- .github/workflows/main.yml | 18 +++++++++ .github/workflows/reference-dev-guide.yml | 49 +++++++++++++++++++++++ reference-dev-guide/README.md | 7 ++++ reference-dev-guide/book.toml | 11 +++++ reference-dev-guide/src/SUMMARY.md | 25 ++++++++++++ 5 files changed, 110 insertions(+) create mode 100644 .github/workflows/reference-dev-guide.yml create mode 100644 reference-dev-guide/README.md create mode 100644 reference-dev-guide/book.toml create mode 100644 reference-dev-guide/src/SUMMARY.md diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2f2b9b29a5..82746b223f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -107,6 +107,23 @@ jobs: working-directory: ./xtask run: cargo fmt --check + reference-dev-guide: + name: reference-dev-guide build check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - name: Install mdbook + env: + MDBOOK_VERSION: 0.5.1 + run: | + mkdir bin + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin + echo "$(pwd)/bin" >> $GITHUB_PATH + - name: Check reference-dev-guide build + run: | + cd reference-dev-guide + mdbook build + preview: if: github.event_name == 'pull_request' runs-on: ubuntu-latest @@ -153,6 +170,7 @@ jobs: - code-tests - style-tests - mdbook-spec + - reference-dev-guide # preview is explicitly excluded here since it doesn't run on merge runs-on: ubuntu-latest steps: diff --git a/.github/workflows/reference-dev-guide.yml b/.github/workflows/reference-dev-guide.yml new file mode 100644 index 0000000000..6007693f11 --- /dev/null +++ b/.github/workflows/reference-dev-guide.yml @@ -0,0 +1,49 @@ +name: Deploy reference-dev-guide +on: + push: + branches: + - master + +env: + MDBOOK_VERSION: 0.5.1 + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - name: Install mdbook + run: | + mkdir mdbook + curl -Lf https://github.com/rust-lang/mdBook/releases/download/v${{ env.MDBOOK_VERSION }}/mdbook-v${{ env.MDBOOK_VERSION }}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook + echo `pwd`/mdbook >> $GITHUB_PATH + + - name: Build the book + run: | + cd reference-dev-guide + mdbook build + mkdir out + touch out/.nojekyll + mv book out/reference-dev-guide + + - name: Upload Artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./reference-dev-guide/out + + deploy: + needs: build + + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/reference-dev-guide/README.md b/reference-dev-guide/README.md new file mode 100644 index 0000000000..2daf972ee6 --- /dev/null +++ b/reference-dev-guide/README.md @@ -0,0 +1,7 @@ +# The Rust Reference Developer Guide + +This is the source of the Reference Developer Guide, published at . It is written in Markdown, using the [mdbook] tool to convert to HTML. If you are editing these pages, the best option to view the results is to run `mdbook serve --open`, which will start a web server on localhost that you can visit to view the book, and it will automatically reload each time you edit a page. + +This is published via GitHub Actions to GitHub Pages. + +[mdbook]: https://rust-lang.github.io/mdBook/ diff --git a/reference-dev-guide/book.toml b/reference-dev-guide/book.toml new file mode 100644 index 0000000000..05a532e677 --- /dev/null +++ b/reference-dev-guide/book.toml @@ -0,0 +1,11 @@ +[book] +title = "The Rust Reference Developer Guide" +language = "en" + +[output.html] +git-repository-url = "https://github.com/rust-lang/reference/tree/master/reference-dev-guide" +edit-url-template = "https://github.com/rust-lang/reference/edit/master/reference-dev-guide/{path}" +smart-punctuation = true + +[output.html.search] +use-boolean-and = true diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md new file mode 100644 index 0000000000..70af89b640 --- /dev/null +++ b/reference-dev-guide/src/SUMMARY.md @@ -0,0 +1,25 @@ +# Summary + +- [Introduction]() +- [Contribution process]() +- [Publishing process]() +- [Reference tooling]() + - [Building the Reference]() + - [mdbook-spec]() +- [Tests]() +- [Formatting]() + - [Markdown]() + - [Admonitions]() +- [Language rules]() + - [rustc test annotations]() +- [Examples]() +- [Links]() +- [Rust grammar]() +- [Attributes]() +- [Style guide]() + - [Wording]() + - [Language and grammar]() + - [Punctuation]() +- [Reviewer guide]() + - [Review process flowchart]() +- [Resources]() From b141dcb49d208304a4e80e1f5e2a64cf1bb8eeb2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:18:43 -0800 Subject: [PATCH 02/39] Move the building section to the contributor guide --- README.md | 61 --------------------- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/tooling/building.md | 60 ++++++++++++++++++++ 3 files changed, 61 insertions(+), 62 deletions(-) create mode 100644 reference-dev-guide/src/tooling/building.md diff --git a/README.md b/README.md index 1db891c78f..6a718cd8b2 100644 --- a/README.md +++ b/README.md @@ -11,67 +11,6 @@ There are several pages for those working on the reference: * [Grammar](https://github.com/rust-lang/reference/blob/master/docs/grammar.md): How the grammar syntax works. * [Attribute template](https://github.com/rust-lang/reference/blob/master/docs/attribute-template.md): The standard template for documenting an attribute. -## Building - -To build the Reference, first clone the project: - -```sh -git clone https://github.com/rust-lang/reference.git -cd reference -``` - -(Alternatively, if you don't want to use `git`, [download][] a ZIP file -of the project, extract it using your preferred tool, and rename the -top-level directory to `reference`.) - -[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip - -### Installing mdbook - -The Reference is built using [mdbook]. - -First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests: - -```sh -rustup toolchain install nightly -rustup override set nightly -``` - -Now, ensure you have `mdbook` installed, as this is needed in order to build the Reference: - -```sh -cargo install --locked mdbook -``` - -[mdbook]: https://rust-lang.github.io/mdBook/ - -### Running mdbook - -`mdbook` provides a variety of different commands and options to help you work on the book: - -* `mdbook build --open`: Build the book and open it in a web browser. -* `mdbook serve --open`: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser. - -The book contents are driven by a `SUMMARY.md` file, and every file must be linked there. See for its usage. - -### `SPEC_RELATIVE` - -The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library. - -```sh -SPEC_RELATIVE=0 mdbook serve --open -``` - -The published site at (or local docs using `rustup doc`) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links in will stay within the 1.81.0 directory). - -### `SPEC_DENY_WARNINGS` - -The `SPEC_DENY_WARNINGS=1` environment variable will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content. - -### `SPEC_RUST_ROOT` - -The `SPEC_RUST_ROOT` can be used to point to the directory of a checkout of . This is used by the test-linking feature so that it can find tests linked to reference rules. If this is not set, then the tests won't be linked. - ## Running tests There are several different kinds of tests you can run (these are enforced on CI): diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 70af89b640..d7c3e71983 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -4,7 +4,7 @@ - [Contribution process]() - [Publishing process]() - [Reference tooling]() - - [Building the Reference]() + - [Building the Reference](tooling/building.md) - [mdbook-spec]() - [Tests]() - [Formatting]() diff --git a/reference-dev-guide/src/tooling/building.md b/reference-dev-guide/src/tooling/building.md new file mode 100644 index 0000000000..7ef2e81c0d --- /dev/null +++ b/reference-dev-guide/src/tooling/building.md @@ -0,0 +1,60 @@ +## Building + +To build the Reference, first clone the project: + +```sh +git clone https://github.com/rust-lang/reference.git +cd reference +``` + +(Alternatively, if you don't want to use `git`, [download][] a ZIP file +of the project, extract it using your preferred tool, and rename the +top-level directory to `reference`.) + +[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip + +### Installing mdbook + +The Reference is built using [mdbook]. + +First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests: + +```sh +rustup toolchain install nightly +rustup override set nightly +``` + +Now, ensure you have `mdbook` installed, as this is needed in order to build the Reference: + +```sh +cargo install --locked mdbook +``` + +[mdbook]: https://rust-lang.github.io/mdBook/ + +### Running mdbook + +`mdbook` provides a variety of different commands and options to help you work on the book: + +* `mdbook build --open`: Build the book and open it in a web browser. +* `mdbook serve --open`: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser. + +The book contents are driven by a `SUMMARY.md` file, and every file must be linked there. See for its usage. + +### `SPEC_RELATIVE` + +The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library. + +```sh +SPEC_RELATIVE=0 mdbook serve --open +``` + +The published site at (or local docs using `rustup doc`) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links in will stay within the 1.81.0 directory). + +### `SPEC_DENY_WARNINGS` + +The `SPEC_DENY_WARNINGS=1` environment variable will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content. + +### `SPEC_RUST_ROOT` + +The `SPEC_RUST_ROOT` can be used to point to the directory of a checkout of . This is used by the test-linking feature so that it can find tests linked to reference rules. If this is not set, then the tests won't be linked. From a1cd48e7278bdc56bf22eb6ff2eb2004d5b58d67 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:21:12 -0800 Subject: [PATCH 03/39] Apply some light edits to "Building the Reference" --- reference-dev-guide/src/tooling/building.md | 40 +++++++++++---------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/reference-dev-guide/src/tooling/building.md b/reference-dev-guide/src/tooling/building.md index 7ef2e81c0d..d02ce7b930 100644 --- a/reference-dev-guide/src/tooling/building.md +++ b/reference-dev-guide/src/tooling/building.md @@ -1,4 +1,6 @@ -## Building +# Building the Reference + +## Checking out the source To build the Reference, first clone the project: @@ -7,24 +9,18 @@ git clone https://github.com/rust-lang/reference.git cd reference ``` -(Alternatively, if you don't want to use `git`, [download][] a ZIP file -of the project, extract it using your preferred tool, and rename the -top-level directory to `reference`.) - -[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip - -### Installing mdbook +## Installing mdbook The Reference is built using [mdbook]. -First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests: +First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed to run the tests: ```sh rustup toolchain install nightly rustup override set nightly ``` -Now, ensure you have `mdbook` installed, as this is needed in order to build the Reference: +Now, ensure you have `mdbook` installed, as this is needed to build the Reference: ```sh cargo install --locked mdbook @@ -32,29 +28,37 @@ cargo install --locked mdbook [mdbook]: https://rust-lang.github.io/mdBook/ -### Running mdbook +## Running mdbook -`mdbook` provides a variety of different commands and options to help you work on the book: +`mdbook` provides a variety of commands and options to help you work on the book: -* `mdbook build --open`: Build the book and open it in a web browser. -* `mdbook serve --open`: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser. +- `mdbook build --open`: Builds the book and opens it in a web browser. +- `mdbook serve --open`: Launches a web server on localhost. It automatically rebuilds the book whenever any file changes and reloads your web browser. The book contents are driven by a `SUMMARY.md` file, and every file must be linked there. See for its usage. ### `SPEC_RELATIVE` -The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library. +The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to instead of being relative. This is useful when viewing locally since you normally don't have a copy of the standard library. ```sh SPEC_RELATIVE=0 mdbook serve --open ``` -The published site at (or local docs using `rustup doc`) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links in will stay within the 1.81.0 directory). +The published site at (or local docs using `rustup doc`) does not set this, which means it uses relative links. This supports offline viewing and links to the correct version (for example, links in will stay within the 1.81.0 directory). ### `SPEC_DENY_WARNINGS` -The `SPEC_DENY_WARNINGS=1` environment variable will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content. +The `SPEC_DENY_WARNINGS=1` environment variable turns all warnings generated by `mdbook-spec` into errors. This is used in CI to ensure that there aren't any problems with the book content. + +```sh +SPEC_DENY_WARNINGS=1 mdbook serve --open +``` ### `SPEC_RUST_ROOT` -The `SPEC_RUST_ROOT` can be used to point to the directory of a checkout of . This is used by the test-linking feature so that it can find tests linked to reference rules. If this is not set, then the tests won't be linked. +The `SPEC_RUST_ROOT` environment variable can be used to point to the directory of a checkout of . This is used by the test-linking feature so that it can find tests linked to Reference rules. If this is not set, the tests won't be linked. + +```sh +SPEC_RUST_ROOT=/path/to/rust mdbook serve --open +``` From 8d482831d304b9ec83609256edf8b385f264ad34 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:23:44 -0800 Subject: [PATCH 04/39] Move the publishing process to the contributor guide --- README.md | 12 ------------ reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/publishing.md | 11 +++++++++++ 3 files changed, 12 insertions(+), 13 deletions(-) create mode 100644 reference-dev-guide/src/publishing.md diff --git a/README.md b/README.md index 6a718cd8b2..893ae494d9 100644 --- a/README.md +++ b/README.md @@ -19,15 +19,3 @@ There are several different kinds of tests you can run (these are enforced on CI * `cargo xtask style-check`: This will validate some style checks (see [authoring guide](docs/authoring.md)). * `cargo xtask linkcheck`: This will validate that markdown links aren't broken. * `cargo xtask test-all`: Runs all tests. - -## How is this published? - -The process for getting the reference content into a [Rust release](https://doc.rust-lang.org/reference/#rust-releases) and on the website is: - -1. Changes are merged to this repository. -2. [Triagebot](https://forge.rust-lang.org/triagebot/doc-updates.html) will automatically synchronize this repository to [rust-lang/rust]. This happens every other week. The reference is tracked in [rust-lang/rust] as a [submodule](https://github.com/rust-lang/rust/tree/master/src/doc). - - This will open a PR on [rust-lang/rust] which needs to be merged, and that can take up to several days. -3. At midnight UTC, whatever is on the default branch of [rust-lang/rust] will be a part of that nightly release, and will be published after a few hours to . -4. Following Rust's [release process](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html), every 6 weeks, nightly will be promoted to beta (), and then 6 weeks after that it will be promoted to stable (). - -[rust-lang/rust]: https://github.com/rust-lang/rust/ diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index d7c3e71983..1825f0af7e 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -2,7 +2,7 @@ - [Introduction]() - [Contribution process]() -- [Publishing process]() +- [Publishing process](publishing.md) - [Reference tooling]() - [Building the Reference](tooling/building.md) - [mdbook-spec]() diff --git a/reference-dev-guide/src/publishing.md b/reference-dev-guide/src/publishing.md new file mode 100644 index 0000000000..65a815dc14 --- /dev/null +++ b/reference-dev-guide/src/publishing.md @@ -0,0 +1,11 @@ +# Publishing process + +The process for getting the Reference content into a [Rust release](https://doc.rust-lang.org/reference/#rust-releases) and on the website is: + +1. Changes are merged to this repository. +2. [Triagebot](https://forge.rust-lang.org/triagebot/doc-updates.html) will automatically synchronize this repository to [rust-lang/rust]. This happens every other week. The reference is tracked in [rust-lang/rust] as a [submodule](https://github.com/rust-lang/rust/tree/master/src/doc). + - This will open a PR on [rust-lang/rust] which needs to be merged, and that can take up to several days. +3. At midnight UTC, whatever is on the default branch of [rust-lang/rust] will be a part of that nightly release, and will be published after a few hours to . +4. Following Rust's [release process](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html), every 6 weeks, nightly will be promoted to beta (), and then 6 weeks after that it will be promoted to stable (). + +[rust-lang/rust]: https://github.com/rust-lang/rust/ From 6b6d4294013871ad0601aee8292d3c873a453e79 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:26:45 -0800 Subject: [PATCH 05/39] Move the contributing guide to the introduction --- reference-dev-guide/src/SUMMARY.md | 2 +- CONTRIBUTING.md => reference-dev-guide/src/introduction.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename CONTRIBUTING.md => reference-dev-guide/src/introduction.md (100%) diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 1825f0af7e..50acd0bec0 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -1,6 +1,6 @@ # Summary -- [Introduction]() +- [Introduction](introduction.md) - [Contribution process]() - [Publishing process](publishing.md) - [Reference tooling]() diff --git a/CONTRIBUTING.md b/reference-dev-guide/src/introduction.md similarity index 100% rename from CONTRIBUTING.md rename to reference-dev-guide/src/introduction.md From 47c771d4b7bebf5be0b77955a0fc6dc2c55311ce Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:27:20 -0800 Subject: [PATCH 06/39] Add a forward to the new contributing guide --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..6edf2913c5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing to The Rust Reference + +See the [Reference Developer Guide](https://rust-lang.github.io/reference/reference-dev-guide/) for information on contributing to the Reference. From 548fcd683693a45a5f886bf98766411f097aaddd Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:28:27 -0800 Subject: [PATCH 07/39] Unwrap the introduction --- reference-dev-guide/src/introduction.md | 64 +++++++------------------ 1 file changed, 16 insertions(+), 48 deletions(-) diff --git a/reference-dev-guide/src/introduction.md b/reference-dev-guide/src/introduction.md index cc2acb9767..ce15c82cd7 100644 --- a/reference-dev-guide/src/introduction.md +++ b/reference-dev-guide/src/introduction.md @@ -1,72 +1,40 @@ +# Introduction + Thank you for your interest in contributing to the Rust Reference! -There are a few ways of helping with the reference: critiquing the reference, -editing the reference, fixing incorrect information, adding examples and -glossary entries, and documenting new or otherwise undocumented features in -Rust. - -For a while, the Reference was basically ignored, and Rust continued gaining new -features or changing old ones. It was also basically the introduction document -before the first edition of the Rust book, and constantly in flux from the huge -churn of the language design before v1.0.0. So there's a lot that's wrong, too -teachy for people who should have basic understanding of Rust, or is too shallow -for the Reference. As such, we have the warning saying there's work that needs -to be done. Eventually, we plan to make sure everything is well documented -enough that we can remove the warning. - -It is encouraged for you to read the [introduction] to familiarize yourself with -the kind of content the reference is expected to contain and the conventions it -uses. Also, the [Authoring Guide] provides more detailed guidelines for -formatting and content. +There are a few ways of helping with the reference: critiquing the reference, editing the reference, fixing incorrect information, adding examples and glossary entries, and documenting new or otherwise undocumented features in Rust. + +For a while, the Reference was basically ignored, and Rust continued gaining new features or changing old ones. It was also basically the introduction document before the first edition of the Rust book, and constantly in flux from the huge churn of the language design before v1.0.0. So there's a lot that's wrong, too teachy for people who should have basic understanding of Rust, or is too shallow for the Reference. As such, we have the warning saying there's work that needs to be done. Eventually, we plan to make sure everything is well documented enough that we can remove the warning. + +It is encouraged for you to read the [introduction] to familiarize yourself with the kind of content the reference is expected to contain and the conventions it uses. Also, the [Authoring Guide] provides more detailed guidelines for formatting and content. ## Critiquing the Reference -This is the easiest way to contribute. Basically, as you read the reference, if -you find something confusing, incorrect, or missing, then you can file an issue -against the reference explaining your concerns. +This is the easiest way to contribute. Basically, as you read the reference, if you find something confusing, incorrect, or missing, then you can file an issue against the reference explaining your concerns. ## Editing the Reference -Typos and incorrect links get through from time to time. Should you find them, -we welcome PRs to fix them. Additionally, larger editing jobs that help remove -the number of parentheticals, remove comma splices, italicize term definitions -and other similar tasks are helpful. +Typos and incorrect links get through from time to time. Should you find them, we welcome PRs to fix them. Additionally, larger editing jobs that help remove the number of parentheticals, remove comma splices, italicize term definitions and other similar tasks are helpful. ## Adding examples and glossary entries -Examples are great. Many people will only read examples and ignore the prose. -Ideally, every facet of every feature will have an example. +Examples are great. Many people will only read examples and ignore the prose. Ideally, every facet of every feature will have an example. -Likewise, the reference has a glossary. It doesn't need to explain every facet -of every feature nor contain every definition, but it does need to be expanded -upon. Ideally entries in the glossary link to the associated documentation. +Likewise, the reference has a glossary. It doesn't need to explain every facet of every feature nor contain every definition, but it does need to be expanded upon. Ideally entries in the glossary link to the associated documentation. ## Adding documentation -There are a lot of features that are not documented at all or are documented -poorly. This is the hardest, but definitely most valuable. Pick an unassigned -issue from the [issue tracker], and write about it. +There are a lot of features that are not documented at all or are documented poorly. This is the hardest, but definitely most valuable. Pick an unassigned issue from the [issue tracker], and write about it. -While writing, you may find it handy to have a [playpen] open to test out what -you are documenting. +While writing, you may find it handy to have a [playpen] open to test out what you are documenting. -Feel free to take information from the standard library and Rustonomicon as -appropriate. +Feel free to take information from the standard library and Rustonomicon as appropriate. -Note that we don't write documentation for purely library features such as -threads and IO and we don't write about Rust in the future. Documentation is -written as if the current stable release of Rust is the last release. The -`master` branch of the reference corresponds to what is **stable** on the -`master` branch ("nightly") of [rust-lang/rust]. If you want to write about -Rust in the future, you want [the Unstable book][unstable]. +Note that we don't write documentation for purely library features such as threads and IO and we don't write about Rust in the future. Documentation is written as if the current stable release of Rust is the last release. The `master` branch of the reference corresponds to what is **stable** on the `master` branch ("nightly") of [rust-lang/rust]. If you want to write about Rust in the future, you want [the Unstable book][unstable]. ## Stabilization -When something that alters the language is stabilized, an issue should be -opened on the reference [issue tracker] to track the documentation process. -This should include links to any relevant information, such as the -stabilization PR, the RFC, the tracking issue, and anything else that would be -helpful for writing the documentation. +When something that alters the language is stabilized, an issue should be opened on the reference [issue tracker] to track the documentation process. This should include links to any relevant information, such as the stabilization PR, the RFC, the tracking issue, and anything else that would be helpful for writing the documentation. [Authoring Guide]: docs/authoring.md [introduction]: src/introduction.md From baef3195ef64030ef41de136ae6839638cd83323 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:32:50 -0800 Subject: [PATCH 08/39] Apply some light edits to the introduction This is just some light editing. I expect that this chapter will have larger edits in the future, but I want to defer that till later. --- reference-dev-guide/src/introduction.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/reference-dev-guide/src/introduction.md b/reference-dev-guide/src/introduction.md index ce15c82cd7..21ea155ebe 100644 --- a/reference-dev-guide/src/introduction.md +++ b/reference-dev-guide/src/introduction.md @@ -1,44 +1,42 @@ # Introduction -Thank you for your interest in contributing to the Rust Reference! +Thank you for your interest in contributing to the Rust Reference! This guide provides an overview of how to contribute to the Reference, and serves as a guide for editors and reviewers. -There are a few ways of helping with the reference: critiquing the reference, editing the reference, fixing incorrect information, adding examples and glossary entries, and documenting new or otherwise undocumented features in Rust. +There are a few ways of helping with the Reference: critiquing the Reference, editing the Reference, fixing incorrect information, adding examples and glossary entries, and documenting new or otherwise undocumented features in Rust. -For a while, the Reference was basically ignored, and Rust continued gaining new features or changing old ones. It was also basically the introduction document before the first edition of the Rust book, and constantly in flux from the huge churn of the language design before v1.0.0. So there's a lot that's wrong, too teachy for people who should have basic understanding of Rust, or is too shallow for the Reference. As such, we have the warning saying there's work that needs to be done. Eventually, we plan to make sure everything is well documented enough that we can remove the warning. - -It is encouraged for you to read the [introduction] to familiarize yourself with the kind of content the reference is expected to contain and the conventions it uses. Also, the [Authoring Guide] provides more detailed guidelines for formatting and content. +It is encouraged for you to read the [introduction] of the Reference to familiarize yourself with the kind of content the Reference is expected to contain and the conventions it uses. ## Critiquing the Reference -This is the easiest way to contribute. Basically, as you read the reference, if you find something confusing, incorrect, or missing, then you can file an issue against the reference explaining your concerns. +This is the easiest way to contribute. Basically, as you read the Reference, if you find something confusing, incorrect, or missing, then you can file an issue against the Reference explaining your concerns. ## Editing the Reference -Typos and incorrect links get through from time to time. Should you find them, we welcome PRs to fix them. Additionally, larger editing jobs that help remove the number of parentheticals, remove comma splices, italicize term definitions and other similar tasks are helpful. +Typos and incorrect links get through from time to time. Should you find them, we welcome PRs to fix them. ## Adding examples and glossary entries Examples are great. Many people will only read examples and ignore the prose. Ideally, every facet of every feature will have an example. -Likewise, the reference has a glossary. It doesn't need to explain every facet of every feature nor contain every definition, but it does need to be expanded upon. Ideally entries in the glossary link to the associated documentation. +Likewise, the Reference has a glossary. It doesn't need to explain every facet of every feature nor contain every definition, but it does need to be expanded upon. Ideally entries in the glossary link to the associated documentation. ## Adding documentation There are a lot of features that are not documented at all or are documented poorly. This is the hardest, but definitely most valuable. Pick an unassigned issue from the [issue tracker], and write about it. -While writing, you may find it handy to have a [playpen] open to test out what you are documenting. +While writing, you may find it handy to have a [playground] open to test out what you are documenting. Feel free to take information from the standard library and Rustonomicon as appropriate. -Note that we don't write documentation for purely library features such as threads and IO and we don't write about Rust in the future. Documentation is written as if the current stable release of Rust is the last release. The `master` branch of the reference corresponds to what is **stable** on the `master` branch ("nightly") of [rust-lang/rust]. If you want to write about Rust in the future, you want [the Unstable book][unstable]. +Note that we don't write documentation for purely library features such as threads and IO and we don't write about Rust in the future. Documentation is written as if the current stable release of Rust is the last release. The `master` branch of the Reference corresponds to what is **stable** on the `master` branch ("nightly") of [rust-lang/rust]. If you want to write about Rust in the future, you want [the Unstable book][unstable]. ## Stabilization -When something that alters the language is stabilized, an issue should be opened on the reference [issue tracker] to track the documentation process. This should include links to any relevant information, such as the stabilization PR, the RFC, the tracking issue, and anything else that would be helpful for writing the documentation. +When something that alters the language is stabilized, an issue should be opened on the Reference [issue tracker] to track the documentation process. This should include links to any relevant information, such as the stabilization PR, the RFC, the tracking issue, and anything else that would be helpful for writing the documentation. [Authoring Guide]: docs/authoring.md -[introduction]: src/introduction.md +[introduction]: https://doc.rust-lang.org/nightly/reference/introduction.html [issue tracker]: https://github.com/rust-lang/reference/issues -[playpen]: https://play.rust-lang.org/ +[playground]: https://play.rust-lang.org/ [rust-lang/rust]: https://github.com/rust-lang/rust/ [unstable]: https://doc.rust-lang.org/nightly/unstable-book/ From c9d3c1f282dd123909753c53c61e28f5cc0a75d6 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:57:08 -0800 Subject: [PATCH 09/39] Move the review policy to the contributor guide --- reference-dev-guide/src/SUMMARY.md | 3 +-- {docs => reference-dev-guide/src}/review-policy.md | 0 2 files changed, 1 insertion(+), 2 deletions(-) rename {docs => reference-dev-guide/src}/review-policy.md (100%) diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 50acd0bec0..75f725e4bd 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -20,6 +20,5 @@ - [Wording]() - [Language and grammar]() - [Punctuation]() -- [Reviewer guide]() - - [Review process flowchart]() +- [Review policy](review-policy.md) - [Resources]() diff --git a/docs/review-policy.md b/reference-dev-guide/src/review-policy.md similarity index 100% rename from docs/review-policy.md rename to reference-dev-guide/src/review-policy.md From 997c1a2327941b7bc86fdc74315fc29a0e65dfae Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 20:59:43 -0800 Subject: [PATCH 10/39] Apply some light edits to the review policy --- reference-dev-guide/src/review-policy.md | 31 ++++++++++++++---------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/reference-dev-guide/src/review-policy.md b/reference-dev-guide/src/review-policy.md index 2195c4440c..4613a167f0 100644 --- a/reference-dev-guide/src/review-policy.md +++ b/reference-dev-guide/src/review-policy.md @@ -1,29 +1,36 @@ -Team members are given permission to merge changes from other contributors in the repository. There are different guidelines for reviewing based on the kind of changes being made: +# Review policy + +Team members have permission to merge changes from other contributors in the repository. There are different guidelines for reviewing based on the kind of changes being made: ## Review principles Reviewers and authors should focus on a few key principles during the review process: -* **Understandability**: Language within the Reference should be understandable to most members of the Project. Contributions should assumes that readers are familiar with the rest of the content of the Reference, but, wherever possible, sections should facilitate that understanding by linking to related content. +* **Understandability**: Language within the Reference should be understandable to most members of the Project. Contributions should assume that readers are familiar with the rest of the content of the Reference, but, wherever possible, sections should facilitate that understanding by linking to related content. * **Defensibility**: When the lang-docs team merges a change to the Reference, they are agreeing to take responsibility for it going forward. Team members need to feel confident defending and explaining the correctness of content within the Reference. Whenever possible, changes to the Reference should back up any claims with concise examples to verify correctness. -* **Voice**: Authors are not expected to have competence as a specification writer when drafting new contributions to the Reference. So long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the Reference. Team members will bring editorial experience as part of their reviews and will revise the phrasing, organization, style, etc. to fit the Reference before merging if necessary. +* **Voice**: Authors are not expected to have competence as a specification writer when drafting new contributions to the Reference. As long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the Reference. Team members will bring editorial experience as part of their reviews and will revise the phrasing, organization, style, etc., to fit the Reference before merging if necessary. ## Policy changes -- Significant changes to the policy of how the team operates, such as changes to this document, should have agreement of the team without any blocking objections. -- Minor changes to something like the style enforcement can be made with the review of a team member, as long as there is high confidence that it is unlikely any team member would object (for example, codifying a guideline that is already in practice), and that the change can be easily reversed. +Significant changes to the policy of how the team operates, such as changes to this document, should have the agreement of the team without any blocking objections. + +Minor changes to something like style enforcement can be made with the review from a team member, as long as there is high confidence that it is unlikely any team member would object (for example, codifying a guideline that is already in practice) and that the change can be easily reversed. ## Meaningful content addition or changes -- When adding or changing content in the spec, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence that the changes are correct, and consider themselves well-versed enough in the topic to understand it, or the relevant experts are the author or have been heavily involved in the process. It is up to the reviewer to use their best judgement when to consult. -- Content should always follow the guidelines from the [authoring guide]. +When adding or changing content in the spec, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence that the changes are correct and considers themselves well-versed enough in the topic to understand it, or if the relevant experts are the author or have been heavily involved in the process. It is up to the reviewer to use their best judgment on when to consult. + +Content should always follow the guidelines in this contributor guide. ## Minor content changes -- Minor content changes, such as small cleanups or wording fixes, can be made with the review from a team member without further consultation. + +Minor content changes, such as small cleanups or wording fixes, can be made with the review from a team member without further consultation. ## Tooling changes -- Minor changes to the tooling may be made with a review from a team member. This includes bug fixes, minor additions that are unlikely to have objections, and additions that have already been discussed. -- Major changes, such as a change in how content is authored, or major changes to how the tooling works should be approved by the team without blocking objections. + +Minor changes to the tooling may be made with a review from a team member. This includes bug fixes, minor additions that are unlikely to have objections, and additions that have already been discussed. + +Major changes, such as a change in how content is authored or major changes to how the tooling works, should be approved by the team without blocking objections. ## Review process flowchart @@ -47,9 +54,7 @@ Some PRs try to "sell" the language too much, or try to explain more (or less) t ### Is this well written? -Some PRs are right but are awkwardly worded or have typographical problems. If the changes are small, we'll just add commits to the branch to clean things up, then merge. +Some PRs are correct but are awkwardly worded or have typographical problems. If the changes are small, we'll just add commits to the branch to clean things up, then merge. This policy does not yet cover the process for getting final approval from the relevant teams. - -[authoring guide]: authoring.md From 44b557f34088a248ef970e76894b671c9810730b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 21:01:02 -0800 Subject: [PATCH 11/39] Move the grammar guide to the contributor guide --- docs/authoring.md | 4 ---- reference-dev-guide/src/SUMMARY.md | 2 +- {docs => reference-dev-guide/src}/grammar.md | 0 3 files changed, 1 insertion(+), 5 deletions(-) rename {docs => reference-dev-guide/src}/grammar.md (100%) diff --git a/docs/authoring.md b/docs/authoring.md index 1d09bb2fe2..b415c008ec 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -223,10 +223,6 @@ r[foo.bar.edition2021] > Describe what changed in 2021. ``` -## Grammar - -See [Grammar](grammar.md) for details on how to write grammar rules. - ## Attributes See the [attribute template](attribute-template.md) for how attributes should be formatted. diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 75f725e4bd..89f129ebc5 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -14,7 +14,7 @@ - [rustc test annotations]() - [Examples]() - [Links]() -- [Rust grammar]() +- [Rust grammar](grammar.md) - [Attributes]() - [Style guide]() - [Wording]() diff --git a/docs/grammar.md b/reference-dev-guide/src/grammar.md similarity index 100% rename from docs/grammar.md rename to reference-dev-guide/src/grammar.md From e201fd65a8e2e62f7d872eebd6f9eff85a9fb7a8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 21:02:12 -0800 Subject: [PATCH 12/39] Apply some light edits to the rust grammar chapter --- reference-dev-guide/src/grammar.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/reference-dev-guide/src/grammar.md b/reference-dev-guide/src/grammar.md index 190782bba4..2b05ec3e3a 100644 --- a/reference-dev-guide/src/grammar.md +++ b/reference-dev-guide/src/grammar.md @@ -1,6 +1,6 @@ -# Grammar +# Rust grammar -The Reference grammar is written in markdown code blocks using a modified BNF-like syntax (with a blend of regex and other arbitrary things). The `mdbook-spec` extension parses these rules and converts them to a renderable format, including railroad diagrams. +The Reference grammar is written in markdown code blocks using a modified BNF-like syntax (with a blend of regex and other arbitrary things). The [`mdbook-spec`] extension parses these rules and converts them to a renderable format, including railroad diagrams. The code block should have a lang string with the word "grammar", a comma, and the category of the grammar, like this: @@ -14,7 +14,7 @@ The category is used to group similar productions on the grammar summary page in ## Grammar syntax -The syntax for the grammar itself is pretty close to what is described in the [Notation chapter](../src/notation.md), though there are some rendering differences. +The syntax for the grammar itself is pretty close to what is described in the [Notation chapter], though there are some rendering differences. A "root" production, marked with `@root`, is one that is not used in any other production. @@ -123,6 +123,9 @@ The general format is a series of productions separated by blank lines. The expr ## Automatic linking -The plugin automatically adds markdown link definitions for all the production names on every page. If you want to link directly to a production name, all you need to do is surround it in square brackets, like `[ArrayExpression]`. +The [`mdbook-spec`] plugin automatically adds markdown link definitions for all the production names on every page. If you want to link directly to a production name, all you need to do is surround it in square brackets, like `[ArrayExpression]`. In some cases there might be name collisions with the automatic linking of rule names. In that case, disambiguate with the `grammar-` prefix, such as `[Type][grammar-Type]`. You can also do that if you just feel like being more explicit. + +[`mdbook-spec`]: tooling/mdbook-spec.md +[Notation chapter]: https://doc.rust-lang.org/nightly/reference/notation.html From 7f451ccb9b64bc33bfc494ad546de24681d9e72a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 21:03:38 -0800 Subject: [PATCH 13/39] Move the attribute template to the contributor guide --- docs/authoring.md | 4 ---- reference-dev-guide/src/SUMMARY.md | 2 +- .../src/attributes.md | 0 3 files changed, 1 insertion(+), 5 deletions(-) rename docs/attribute-template.md => reference-dev-guide/src/attributes.md (100%) diff --git a/docs/authoring.md b/docs/authoring.md index b415c008ec..ccda76d895 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -222,7 +222,3 @@ r[foo.bar.edition2021] > [!EDITION-2021] > Describe what changed in 2021. ``` - -## Attributes - -See the [attribute template](attribute-template.md) for how attributes should be formatted. diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 89f129ebc5..2d42b7c9f7 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -15,7 +15,7 @@ - [Examples]() - [Links]() - [Rust grammar](grammar.md) -- [Attributes]() +- [Attributes](attributes.md) - [Style guide]() - [Wording]() - [Language and grammar]() diff --git a/docs/attribute-template.md b/reference-dev-guide/src/attributes.md similarity index 100% rename from docs/attribute-template.md rename to reference-dev-guide/src/attributes.md From 561ccfd3898eed07bfb97e9f89e3297f47be56c1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Nov 2025 21:04:18 -0800 Subject: [PATCH 14/39] Update attributes chapter title --- reference-dev-guide/src/attributes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference-dev-guide/src/attributes.md b/reference-dev-guide/src/attributes.md index 07990e501a..4f886dbc1e 100644 --- a/reference-dev-guide/src/attributes.md +++ b/reference-dev-guide/src/attributes.md @@ -1,4 +1,4 @@ -# Attribute template +# Attributes Attributes should use the following template. Examples are given for phrasing you *should* use, but you should deviate if the attribute doesn't fit any of the examples or if they get in the way of clarity. From 4b8797a9a7beb430dcddbc5b33c91171654b0fa9 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 06:55:03 -0800 Subject: [PATCH 15/39] Add a chapter describing mdbook-spec --- reference-dev-guide/src/SUMMARY.md | 2 +- .../src/tooling/mdbook-spec.md | 39 +++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 reference-dev-guide/src/tooling/mdbook-spec.md diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 2d42b7c9f7..cbdc359741 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -5,7 +5,7 @@ - [Publishing process](publishing.md) - [Reference tooling]() - [Building the Reference](tooling/building.md) - - [mdbook-spec]() + - [mdbook-spec](tooling/mdbook-spec.md) - [Tests]() - [Formatting]() - [Markdown]() diff --git a/reference-dev-guide/src/tooling/mdbook-spec.md b/reference-dev-guide/src/tooling/mdbook-spec.md new file mode 100644 index 0000000000..13ed32b6a2 --- /dev/null +++ b/reference-dev-guide/src/tooling/mdbook-spec.md @@ -0,0 +1,39 @@ +# mdbook-spec + +[`mdbook-spec`] is an mdBook preprocessor that adds features to the Reference. It provides: + +- Parsing and generation of [grammar diagrams]. + - [Automatic grammar production links]. + - Generation of the [grammar summary appendix]. +- [Automatic standard library links]. +- Handling of [rule names]. + - Validation of the names. + - Converting rule names to links. + - [Automatic rule link references]. + - Generation of [links to rule tests]. + - Generation of the [test summary]. +- Support for [admonitions]. + +## Environment variables + +There are a few environment variables that `mdbook-spec` uses, described in the [building chapter]: + +- [`SPEC_RELATIVE`] --- Can be set to link external books to the live site. +- [`SPEC_DENY_WARNINGS`] --- Whether warnings should be treated as errors. +- [`SPEC_RUST_ROOT`] --- The path to a checkout of the [`rust-lang/rust`] GitHub repository. This is used for test linking. + +[`mdbook-spec`]: https://github.com/rust-lang/reference/tree/master/mdbook-spec +[`rust-lang/rust`]: https://github.com/rust-lang/rust +[`SPEC_DENY_WARNINGS`]: building.md#SPEC_DENY_WARNINGS +[`SPEC_RELATIVE`]: building.md#SPEC_RELATIVE +[`SPEC_RUST_ROOT`]: building.md#SPEC_RUST_ROOT +[admonitions]: ../formatting/admonitions.md +[Automatic grammar production links]: ../grammar.md#automatic-linking +[Automatic rule link references]: ../links.md#rule-links +[Automatic standard library links]: ../links.md#standard-library-links +[Building chapter]: building.md +[grammar diagrams]: ../grammar.md +[grammar summary appendix]: https://doc.rust-lang.org/nightly/reference/grammar.html +[links to rule tests]: ../rules/test-annotations.md +[rule names]: ../rules/index.md +[test summary]: https://doc.rust-lang.org/nightly/reference/test-summary.html From 09fa9d6f209d60c9fb6b7dd3531617ae97ade149 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 06:58:47 -0800 Subject: [PATCH 16/39] Start a formatting chapter --- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/formatting/index.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 reference-dev-guide/src/formatting/index.md diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index cbdc359741..5a5ad531b4 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -7,7 +7,7 @@ - [Building the Reference](tooling/building.md) - [mdbook-spec](tooling/mdbook-spec.md) - [Tests]() -- [Formatting]() +- [Formatting](formatting/index.md) - [Markdown]() - [Admonitions]() - [Language rules]() diff --git a/reference-dev-guide/src/formatting/index.md b/reference-dev-guide/src/formatting/index.md new file mode 100644 index 0000000000..58b739bfc3 --- /dev/null +++ b/reference-dev-guide/src/formatting/index.md @@ -0,0 +1,3 @@ +# Formatting + +The following chapters detail how the Reference source should be formatted. From a5ca52f49e6763f046a20858759b0ebb65fb68cc Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:03:34 -0800 Subject: [PATCH 17/39] Move markdown formatting to the contributor guide --- docs/authoring.md | 31 ------------- reference-dev-guide/src/SUMMARY.md | 2 +- .../src/formatting/markdown.md | 45 +++++++++++++++++++ 3 files changed, 46 insertions(+), 32 deletions(-) create mode 100644 reference-dev-guide/src/formatting/markdown.md diff --git a/docs/authoring.md b/docs/authoring.md index ccda76d895..7e806511ba 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -4,37 +4,6 @@ This document serves as a guide for editors and reviewers. Some conventions and [introduction]: ../src/introduction.md -## Markdown formatting - -* Use [ATX-style headings][atx] (not Setext) with [sentence case]. -* Do not use tabs, only spaces. -* Files must end with a newline. -* Lines must not end with spaces. Double spaces have semantic meaning, but can be invisible. Use a trailing backslash if you need a hard line break. -* If possible, avoid double blank lines. -* Do not use indented code blocks; use 3+ backticks code blocks instead. -* Code blocks should have an explicit language tag. -* Do not wrap long lines. This helps with reviewing diffs of the source. -* Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. -* Links should be relative with the `.md` extension. Links to other rust-lang books that are published with the reference should also be relative so that the linkchecker can validate them. -* Links to the standard library should use rustdoc-style links described in [Standard library links](#standard-library-links). -* The use of reference links is preferred, with shortcuts if appropriate. Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there are an unusually large number of links that are specific to the section. - - ```markdown - Example of shortcut link: [enumerations] - Example of reference link with label: [block expression][block] - - [block]: expressions/block-expr.md - [enumerations]: types/enum.md - ``` -* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings. - -There are automated checks for some of these rules. Run `cargo xtask style-check` to run them locally. - -[atx]: https://spec.commonmark.org/0.31.2/#atx-headings -[conventions]: ../src/introduction.md#conventions -[sentence case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case -[smart punctuation]: https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation - ### Code examples Code examples should use code blocks with triple backticks. The language should always be specified (such as `rust`). diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 5a5ad531b4..e1278f5d0e 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -8,7 +8,7 @@ - [mdbook-spec](tooling/mdbook-spec.md) - [Tests]() - [Formatting](formatting/index.md) - - [Markdown]() + - [Markdown](formatting/markdown.md) - [Admonitions]() - [Language rules]() - [rustc test annotations]() diff --git a/reference-dev-guide/src/formatting/markdown.md b/reference-dev-guide/src/formatting/markdown.md new file mode 100644 index 0000000000..3ae9d78d13 --- /dev/null +++ b/reference-dev-guide/src/formatting/markdown.md @@ -0,0 +1,45 @@ +# Markdown + +There are automated checks for some of these rules. Run [`cargo xtask style-check`] to run them locally. + +## Formatting style + +- Use [ATX-style headings][atx] (not Setext) with [sentence case]. +- Do not use tabs, only spaces. +- Files must end with a newline. +- Lines must not end with spaces. Double spaces have semantic meaning, but can be invisible. Use a trailing backslash if you need a hard line break. +- If possible, avoid double blank lines. +- Do not wrap long lines. This helps with reviewing diffs of the source. +- Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. +- See the [admonitions chapter] for formatting callouts such as notes, edition differences, and warnings. + +## Code blocks + +- Do not use indented code blocks; use 3+ backticks code blocks instead. +- Code blocks should have an explicit language tag. + +## Links + +See the [links chapter] for more information about linking. + +- Links to other chapters should be relative with the `.md` extension. +- Links to other rust-lang books that are published with the Reference should also be relative so that the linkchecker can validate them. See [outside book links]. +- Links to the standard library should use rustdoc-style links described in [standard library links]. +- The use of reference links is preferred, with shortcuts if appropriate. Place the sorted link reference definitions at the bottom of the file or at the bottom of a section if there are an unusually large number of links that are specific to the section. + + ```markdown + Example of shortcut link: [enumerations] + Example of reference link with label: [block expression][block] + + [block]: expressions/block-expr.md + [enumerations]: types/enum.md + ``` + +[`cargo xtask style-check`]: ../tests.md#style-checks +[admonitions chapter]: admonitions.md +[atx]: https://spec.commonmark.org/0.31.2/#atx-headings +[links chapter]: ../links.md +[outside book links]: ../links.md#outside-book-links +[sentence case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case +[smart punctuation]: https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation +[standard library links]: ../links.md#standard-library-links From 01b3202da98fe164061f0fd2525a834717ae8989 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:05:32 -0800 Subject: [PATCH 18/39] Move admonitions to the contributor guide --- docs/authoring.md | 20 ---------------- reference-dev-guide/src/SUMMARY.md | 2 +- .../src/formatting/admonitions.md | 23 +++++++++++++++++++ 3 files changed, 24 insertions(+), 21 deletions(-) create mode 100644 reference-dev-guide/src/formatting/admonitions.md diff --git a/docs/authoring.md b/docs/authoring.md index 7e806511ba..8b9667fe29 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -141,26 +141,6 @@ When running into a rustdoc limitation, consider manually linking to the correct [intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html -### Admonitions - -Admonitions use a style similar to GitHub-flavored markdown, where the style name is placed at the beginning of a blockquote, such as: - -```markdown -> [!WARNING] -> This is a warning. - -> [!NOTE] -> This is a note. - -> [!EDITION-2024] -> This is an edition-specific difference. - -> [!EXAMPLE] -> This is an example. -``` - -The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/admonitions.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/admonitions.rs). - ## Style Idioms and styling: diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index e1278f5d0e..c20908f8ec 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -9,7 +9,7 @@ - [Tests]() - [Formatting](formatting/index.md) - [Markdown](formatting/markdown.md) - - [Admonitions]() + - [Admonitions](formatting/admonitions.md) - [Language rules]() - [rustc test annotations]() - [Examples]() diff --git a/reference-dev-guide/src/formatting/admonitions.md b/reference-dev-guide/src/formatting/admonitions.md new file mode 100644 index 0000000000..db18339fa7 --- /dev/null +++ b/reference-dev-guide/src/formatting/admonitions.md @@ -0,0 +1,23 @@ +# Admonitions + +[`mdbook-spec`](../tooling/mdbook-spec.md) provides admonitions which use a style similar to GitHub-flavored markdown. The style name is placed at the beginning of a blockquote, such as: + +```markdown +> [!WARNING] +> This is a warning. + +> [!NOTE] +> This is a note. + +> [!EDITION-2024] +> This is an edition-specific difference. + +> [!EXAMPLE] +> This is an example. +``` + +The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/admonitions.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/admonitions.rs). + +See the [conventions section] for a description of how these should be used. + +[conventions section]: https://doc.rust-lang.org/nightly/reference/#conventions From e54440a113b2439a472e4a46b36935a04b67677a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:12:25 -0800 Subject: [PATCH 19/39] Move examples to the contributor guide --- docs/authoring.md | 27 --------------------- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/examples.md | 37 +++++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 28 deletions(-) create mode 100644 reference-dev-guide/src/examples.md diff --git a/docs/authoring.md b/docs/authoring.md index 8b9667fe29..61dd2877b5 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -4,33 +4,6 @@ This document serves as a guide for editors and reviewers. Some conventions and [introduction]: ../src/introduction.md -### Code examples - -Code examples should use code blocks with triple backticks. The language should always be specified (such as `rust`). - -```rust -println!("Hello!"); -``` - -See for a list of supported languages. - -Rust examples are tested via rustdoc, and should include the appropriate annotations: - -* `edition2015`, `edition2018`, etc. --- If it is edition-specific (see `book.toml` for the default). -* `no_run` --- The example should compile successfully, but should not be executed. -* `should_panic` --- The example should compile and run, but produce a panic. -* `compile_fail` --- The example is expected to fail to compile. -* `ignore` --- The example shouldn't be built or tested. This should be avoided if possible. Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. An HTML comment such as `` should be placed before the example to explain why it is ignored. -* `Exxxx` --- If the example is expected to fail to compile with a specific error code, include that code so that rustdoc will check that the expected code is used. - -When demonstrating success cases, many such cases may be included in a single code block. For failure cases, however, each example must appear in a separate code block so that the tests can ensure that each case indeed fails and fails with the appropriate error code or codes. - -See the [rustdoc documentation] for more detail. - -[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html - -You can verify the samples pass by running `mdbook test`. - ### Linkcheck To verify that links are not broken, run `cargo xtask linkcheck`. diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index c20908f8ec..fbb7184708 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -12,7 +12,7 @@ - [Admonitions](formatting/admonitions.md) - [Language rules]() - [rustc test annotations]() -- [Examples]() +- [Examples](examples.md) - [Links]() - [Rust grammar](grammar.md) - [Attributes](attributes.md) diff --git a/reference-dev-guide/src/examples.md b/reference-dev-guide/src/examples.md new file mode 100644 index 0000000000..19bdd0f77a --- /dev/null +++ b/reference-dev-guide/src/examples.md @@ -0,0 +1,37 @@ +# Examples + +## Example code blocks + +Code examples should use code blocks with triple backticks. The language should always be specified (such as `rust`). + +```rust +println!("Hello!"); +``` + +See the [mdBook supported languages] for a list of supported languages. + +## rustdoc attributes + +Rust examples are [tested via rustdoc], and should include the appropriate annotations: + +- `edition2015`, `edition2018`, etc. --- If it is edition-specific (see `book.toml` for the default). +- `no_run` --- The example should compile successfully, but should not be executed. +- `should_panic` --- The example should compile and run, but produce a panic. +- `compile_fail` --- The example is expected to fail to compile. +- `ignore` --- The example shouldn't be built or tested. This should be avoided if possible. Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. An HTML comment such as `` should be placed before the example to explain why it is ignored. +- `Exxxx` --- If the example is expected to fail to compile with a specific error code, include that code so that rustdoc will check that the expected code is used. + +See the [rustdoc documentation] for more detail. + +## Combining examples + +When demonstrating success cases, many such cases may be included in a single code block. For failure cases, however, each example must appear in a separate code block so that the tests can ensure that each case indeed fails and fails with the appropriate error code or codes. + +## Testing examples + +The Rust code blocks are tested in CI. You can verify the samples pass by running [`mdbook test`]. + +[`mdbook test`]: tests.md#inline-tests +[mdBook supported languages]: https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting.html#supported-languages +[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html +[tested via rustdoc]: tests.md#inline-tests From 7bf73a49ef298e17da6c7f46866add24a48e0b10 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:26:38 -0800 Subject: [PATCH 20/39] Move standard library links to the links chapter --- docs/authoring.md | 45 ------------------------- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/links.md | 53 ++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 46 deletions(-) create mode 100644 reference-dev-guide/src/links.md diff --git a/docs/authoring.md b/docs/authoring.md index 61dd2877b5..a62e06f26a 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -69,51 +69,6 @@ We are not expecting 100% coverage at any time. Although it would be nice, it is [appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html -### Standard library links - -You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: - -We can link to the page on `Option`: - -```markdown -[`std::option::Option`] -``` - -In these links, generics are ignored and can be included: - -```markdown -[`std::option::Option`] -``` - -If we don't want the full path in the text, we can write: - -```markdown -[`Option`](std::option::Option) -``` - -Macros can end in `!`. This can be helpful for disambiguation. For example, this refers to the macro rather than the module: - -```markdown -[`alloc::vec!`] -``` - -Explicit namespace disambiguation is also supported: - -```markdown -[`std::vec`](mod@std::vec) -``` - -Beware there are some limitations, for example: - -- Links to rexports from `std_arch` don't work due to . -- Links to keywords aren't supported. -- Links to trait impls where the trait is not in the prelude doesn't work. Traits must be in scope, and there currently isn't a way to add those. -- If there are multiple generic implementations, it will link to one randomly (see ). - -When running into a rustdoc limitation, consider manually linking to the correct page using a relative link. For example, `../std/arch/macro.is_x86_feature_detected.html`. - -[intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html - ## Style Idioms and styling: diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index fbb7184708..162f962e6f 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -13,7 +13,7 @@ - [Language rules]() - [rustc test annotations]() - [Examples](examples.md) -- [Links]() +- [Links](links.md) - [Rust grammar](grammar.md) - [Attributes](attributes.md) - [Style guide]() diff --git a/reference-dev-guide/src/links.md b/reference-dev-guide/src/links.md new file mode 100644 index 0000000000..2d83b8448e --- /dev/null +++ b/reference-dev-guide/src/links.md @@ -0,0 +1,53 @@ +# Links + +This chapter explains how links should be handled by the Reference. Several of these capabilities are provided by [`mdbook-spec`](tooling/mdbook-spec.md). + +See also the [linkchecker tests](tests.md#linkcheck) for testing links. + +## Standard library links + +You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: + +We can link to the page on `Option`: + +```markdown +[`std::option::Option`] +``` + +In these links, generics are ignored and can be included: + +```markdown +[`std::option::Option`] +``` + +If we don't want the full path in the text, we can write: + +```markdown +[`Option`](std::option::Option) +``` + +Macros can end in `!`. This can be helpful for disambiguation. For example, this refers to the macro rather than the module: + +```markdown +[`alloc::vec!`] +``` + +Explicit namespace disambiguation is also supported: + +```markdown +[`std::vec`](mod@std::vec) +``` + +Beware there are some limitations, for example: + +- Links to rexports from `std_arch` don't work due to . +- Links to keywords aren't supported. +- Links to trait impls where the trait is not in the prelude doesn't work. Traits must be in scope, and there currently isn't a way to add those. +- If there are multiple generic implementations, it will link to one randomly (see ). + +When running into a rustdoc limitation, consider manually linking to the correct page using a relative link. For example, `../std/arch/macro.is_x86_feature_detected.html`. + +When rendering the Reference locally, by default it uses relative links to conform with how the books are published. This probably isn't what you want, so you usually will want to set the [`SPEC_RELATIVE=0` environment variable][rel] so that the links go to the live site instead. + +[intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html +[rel]: tooling/building.md#spec_relative From d03126def6c75b2f139bb0ed16925de32403e546 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:31:52 -0800 Subject: [PATCH 21/39] Add more details to the links chapter --- reference-dev-guide/src/links.md | 44 ++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/reference-dev-guide/src/links.md b/reference-dev-guide/src/links.md index 2d83b8448e..d1629db41b 100644 --- a/reference-dev-guide/src/links.md +++ b/reference-dev-guide/src/links.md @@ -4,6 +4,20 @@ This chapter explains how links should be handled by the Reference. Several of t See also the [linkchecker tests](tests.md#linkcheck) for testing links. +## Rule links + +[Rules](rules/index.md) can be linked to by their ID using Markdown, with the destination set to the rule ID. Automatic link references allow any rule to be referred to from any page in the book. + +```markdown +Direct label link: [names.preludes.lang] + +Destination label link (custom link text): [language prelude][names.preludes.lang] + +Definition link: [namespace kinds] + +[namespace kinds]: names.namespaces.kinds +``` + ## Standard library links You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: @@ -51,3 +65,33 @@ When rendering the Reference locally, by default it uses relative links to confo [intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html [rel]: tooling/building.md#spec_relative + +## Grammar links + +Link definitions are automatically generated for all grammar production names. See [grammar automatic linking](grammar.md#automatic-linking) for more. + +```markdown +This attribute uses the [MetaWord] syntax. + +Explicit grammar links can have the `grammar-` prefix like [Type][grammar-Type]. +``` + +## Outside book links + +Links to other books published with the Reference should be relative links pointing to the corresponding book. This allows the links to point to the correct version, to work with the offline docs, and to be checked by the linkchecker. For example: + +```markdown +See [`-C panic`]. + +[`-C panic`]: ../rustc/codegen-options/index.html#panic +``` + +## Internal links + +When possible, internal links should use [rule links](#rule-links) or [grammar links](#grammar-links). Otherwise, links should be relative to the file path and use the `.md` extension. + +```markdown +- Rule link: [language prelude][names.preludes.lang] +- Grammar link: [MetaWord] +- Internal link: [Modules](items/modules.md#attributes-on-modules) +``` From c1e660ff0b205ea356d5a81d1bac933641f6f92a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:35:16 -0800 Subject: [PATCH 22/39] Move rules to the contributor guide --- docs/authoring.md | 57 ------------------- reference-dev-guide/src/SUMMARY.md | 4 +- reference-dev-guide/src/rules/index.md | 44 ++++++++++++++ .../src/rules/test-annotations.md | 15 +++++ 4 files changed, 61 insertions(+), 59 deletions(-) create mode 100644 reference-dev-guide/src/rules/index.md create mode 100644 reference-dev-guide/src/rules/test-annotations.md diff --git a/docs/authoring.md b/docs/authoring.md index a62e06f26a..cc7247b8f7 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -12,63 +12,6 @@ To verify that links are not broken, run `cargo xtask linkcheck`. As a last step before opening a PR, it is recommended to run `cargo xtask test-all`. This will go through and run most of the tests that are required for CI to pass. See `xtask/src/main.rs` for what all this does. -## Special markdown constructs - -The following are extensions provided by [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec). - -### Rules - -Most clauses should be preceded with a rule. Rules can be specified in the markdown source with the following on a line by itself: - -```markdown -r[foo.bar] -``` - -The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`). - -Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are automatic link references so that any rule can be referred to from any page in the book. - -In the HTML, the rules are clickable just like headers. - -When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: - -1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to. -2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break. - * This content will be moved to `[!NOTE]` or more specific admonitions in the future. -3. Rust code examples and tests do not need their own rules. -4. Use the following guidelines for admonitions: - * Notes: Do not include a rule. - * Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. - * Target specific behavior: Always include the rule. - * Edition differences: Always include the rule. -5. The following keywords should be used to identify paragraphs when unambiguous: - * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. - * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used. - * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`). -6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows: - * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). - * Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule". - * Whenever possible, do not repeat previous components of the rule. - * Edition differences admonitions should typically be named by the edition where the behavior changed. You should be able to correspond the dates to the chapters in . - * Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). - * Use an appropriately descriptive, but short, name if the language does not provide one. - -#### Test rule annotations - -Tests in can be linked to rules in the reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked. - -Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link it to a rule. The header can be specified multiple times if a single file covers multiple rules. - -Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for making sure every rule has a test associated with it. - -The tests are beneficial for reviewers to see the behavior of a rule. It is also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names). - -Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`. - -We are not expecting 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence things are developed, and resources available. - -[appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html - ## Style Idioms and styling: diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 162f962e6f..6d9a37b0d9 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -10,8 +10,8 @@ - [Formatting](formatting/index.md) - [Markdown](formatting/markdown.md) - [Admonitions](formatting/admonitions.md) -- [Language rules]() - - [rustc test annotations]() +- [Language rules](rules/index.md) + - [rustc test annotations](rules/test-annotations.md) - [Examples](examples.md) - [Links](links.md) - [Rust grammar](grammar.md) diff --git a/reference-dev-guide/src/rules/index.md b/reference-dev-guide/src/rules/index.md new file mode 100644 index 0000000000..5dd923de9b --- /dev/null +++ b/reference-dev-guide/src/rules/index.md @@ -0,0 +1,44 @@ +# Language rules + +Clauses within the Reference are labeled with a named *rule*. This provides the ability to link and refer to individual clauses, and to [link to the `rustc` testsuite](test-annotations.md). + +## Rule labels + +Most clauses should be preceded with a rule label. A rule label should be on a line by itself, and should look like this: + +```markdown +r[foo.bar] +``` + +The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`). + +Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are [automatic link references] so that any rule can be referred to from any page in the book. + +In the HTML, the rules are clickable just like headers. + +## Rule guidelines + +When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: + +1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to. +2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break. + - This content will be moved to `[!NOTE]` or more specific admonitions in the future. +3. Rust code examples and tests do not need their own rules. +4. Use the following guidelines for admonitions: + - Notes: Do not include a rule. + - Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. + - Target specific behavior: Always include the rule. + - Edition differences: Always include the rule. +5. The following keywords should be used to identify paragraphs when unambiguous: + - `intro`: The beginning paragraph of each section - should explain the construct being defined overall. + - `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used. + - `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`). +6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows: + - If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). + - Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule". + - Whenever possible, do not repeat previous components of the rule. + - Edition differences admonitions should typically be named by the edition where the behavior changed. You should be able to correspond the dates to the chapters in . + - Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). + - Use an appropriately descriptive, but short, name if the language does not provide one. + +[automatic link references]: ../links.md#rule-links diff --git a/reference-dev-guide/src/rules/test-annotations.md b/reference-dev-guide/src/rules/test-annotations.md new file mode 100644 index 0000000000..be01c2307d --- /dev/null +++ b/reference-dev-guide/src/rules/test-annotations.md @@ -0,0 +1,15 @@ +# rustc test annotations + +Tests in can be linked to rules in the reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked. + +Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link it to a rule. The header can be specified multiple times if a single file covers multiple rules. + +Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for making sure every rule has a test associated with it. + +The tests are beneficial for reviewers to see the behavior of a rule. It is also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names). + +Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`. + +We are not expecting 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence things are developed, and resources available. + +[appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html From c75fcb9dbbf3b0b2e50621cf9fc1a1f43975abaf Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:40:04 -0800 Subject: [PATCH 23/39] Add a contributor tests chapter --- docs/authoring.md | 8 ---- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/tests.md | 60 ++++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+), 9 deletions(-) create mode 100644 reference-dev-guide/src/tests.md diff --git a/docs/authoring.md b/docs/authoring.md index cc7247b8f7..7eaff0949c 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -4,14 +4,6 @@ This document serves as a guide for editors and reviewers. Some conventions and [introduction]: ../src/introduction.md -### Linkcheck - -To verify that links are not broken, run `cargo xtask linkcheck`. - -### Running all tests - -As a last step before opening a PR, it is recommended to run `cargo xtask test-all`. This will go through and run most of the tests that are required for CI to pass. See `xtask/src/main.rs` for what all this does. - ## Style Idioms and styling: diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 6d9a37b0d9..321f6a6e47 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -6,7 +6,7 @@ - [Reference tooling]() - [Building the Reference](tooling/building.md) - [mdbook-spec](tooling/mdbook-spec.md) -- [Tests]() +- [Tests](tests.md) - [Formatting](formatting/index.md) - [Markdown](formatting/markdown.md) - [Admonitions](formatting/admonitions.md) diff --git a/reference-dev-guide/src/tests.md b/reference-dev-guide/src/tests.md new file mode 100644 index 0000000000..4cbcd4e574 --- /dev/null +++ b/reference-dev-guide/src/tests.md @@ -0,0 +1,60 @@ +# Running tests + +There are several different kinds of tests you can run (these are enforced in CI): + +- [`cargo xtask test-all`](#all-tests) --- Runs all tests. +- [`mdbook test`](#inline-tests) --- Tests the inline Rust codeblocks. +- [`cargo xtask linkcheck`](#linkcheck) --- Validates that markdown links aren't broken. +- [`cargo xtask style-check`](#style-checks) --- Validates various style checks. +- [Code formatting](#code-formatting) --- Checks that all Rust tooling code is formatted. +- [mdbook-spec tests](#mdbook-spec-tests) --- Internal tests for `mdbook-spec`. + +## All tests + +```sh +cargo xtask test-all +``` + +This command runs all the tests listed below. + +We recommend running this as a last step before opening a PR. This runs most of the tests required for CI to pass. See [`xtask/src/main.rs`](https://github.com/rust-lang/reference/blob/master/xtask/src/main.rs) for details on what this does. + +## Inline tests + +```sh +mdbook test +``` + +This command runs all tests that are inline in the Markdown. Internally, this uses [`rustdoc`](https://doc.rust-lang.org/rustdoc/) to run the tests and supports all the same features. Any code block with the `rust` language will be compiled unless it is ignored. See the [Examples chapter](examples.md) for more. + +## Linkcheck + +```sh +cargo xtask linkcheck +``` + +This command verifies that links are not broken. It downloads and uses the [`linkchecker`](https://github.com/rust-lang/rust/tree/main/src/tools/linkchecker) script hosted in the `rust-lang/rust` repository. + +This requires a recent nightly installed via `rustup` and the `rust-docs` component. + +After compiling the script, it builds the Reference using `mdbook` and then scans all local links to verify that they are valid, particularly between various books. This does not check any network links. + +## Style checks + +```sh +cargo xtask style-check +``` + +This uses the [`style-check`](https://github.com/rust-lang/reference/tree/master/style-check) tool to enforce various formatting rules. + +## Code formatting + +CI uses `cargo fmt --check` to verify that all Rust sources for the tools (like `mdbook-spec`) are properly formatted. All code must be formatted with `rustfmt`. + +## mdbook-spec tests + +```sh +cargo test --manifest-path mdbook-spec/Cargo.toml +``` + +CI runs `cargo test` on `mdbook-spec` to execute any tests for the tool itself. From 34ddfe63549535934ed50c2cd8a5f7a7fef4db0d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:42:31 -0800 Subject: [PATCH 24/39] Start a style guide --- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/style/index.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 reference-dev-guide/src/style/index.md diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 321f6a6e47..268688177e 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -16,7 +16,7 @@ - [Links](links.md) - [Rust grammar](grammar.md) - [Attributes](attributes.md) -- [Style guide]() +- [Style guide](style/index.md) - [Wording]() - [Language and grammar]() - [Punctuation]() diff --git a/reference-dev-guide/src/style/index.md b/reference-dev-guide/src/style/index.md new file mode 100644 index 0000000000..2c18cf82b2 --- /dev/null +++ b/reference-dev-guide/src/style/index.md @@ -0,0 +1,3 @@ +# Style guide + +The following chapters are the preferred style guide for English prose in the Reference. From cf6be1adb728375cd7a2171b3562c01572328dc0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:44:26 -0800 Subject: [PATCH 25/39] Start the wording style chapter This is just a stub, with the expectation that it will be expanded/rewritten later. --- docs/authoring.md | 2 -- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/style/wording.md | 5 +++++ 3 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 reference-dev-guide/src/style/wording.md diff --git a/docs/authoring.md b/docs/authoring.md index 7eaff0949c..41a37d4e1d 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -8,10 +8,8 @@ This document serves as a guide for editors and reviewers. Some conventions and Idioms and styling: -* Use American English spelling. * Use Oxford commas. * Avoid slashes for alternatives ("program/binary"); use conjunctions or rewrite it ("program or binary"). -* Avoid qualifying something as "in Rust"; the entire reference is about Rust. ## Content guidelines diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 268688177e..dc7c892d58 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -17,7 +17,7 @@ - [Rust grammar](grammar.md) - [Attributes](attributes.md) - [Style guide](style/index.md) - - [Wording]() + - [Wording](style/wording.md) - [Language and grammar]() - [Punctuation]() - [Review policy](review-policy.md) diff --git a/reference-dev-guide/src/style/wording.md b/reference-dev-guide/src/style/wording.md new file mode 100644 index 0000000000..26a6b26e4f --- /dev/null +++ b/reference-dev-guide/src/style/wording.md @@ -0,0 +1,5 @@ +# Wording + +Use American English spelling. + +Avoid qualifying something as "in Rust"; the entire Reference is about Rust. From 2d4a6f2e19dbff287807ee17e694447df858bcf3 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:45:37 -0800 Subject: [PATCH 26/39] Start the punctuation chapter This is just a stub, with the expectation that it will be expanded/rewritten later. --- docs/authoring.md | 7 ------- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/style/punctuation.md | 5 +++++ 3 files changed, 6 insertions(+), 8 deletions(-) create mode 100644 reference-dev-guide/src/style/punctuation.md diff --git a/docs/authoring.md b/docs/authoring.md index 41a37d4e1d..f23b8b79b2 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -4,13 +4,6 @@ This document serves as a guide for editors and reviewers. Some conventions and [introduction]: ../src/introduction.md -## Style - -Idioms and styling: - -* Use Oxford commas. -* Avoid slashes for alternatives ("program/binary"); use conjunctions or rewrite it ("program or binary"). - ## Content guidelines The following are guidelines for the content of the reference. diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index dc7c892d58..b7103ace10 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -19,6 +19,6 @@ - [Style guide](style/index.md) - [Wording](style/wording.md) - [Language and grammar]() - - [Punctuation]() + - [Punctuation](style/punctuation.md) - [Review policy](review-policy.md) - [Resources]() diff --git a/reference-dev-guide/src/style/punctuation.md b/reference-dev-guide/src/style/punctuation.md new file mode 100644 index 0000000000..cba6be2016 --- /dev/null +++ b/reference-dev-guide/src/style/punctuation.md @@ -0,0 +1,5 @@ +# Punctuation + +Use Oxford commas. + +Avoid slashes for alternatives ("program/binary"); use conjunctions or rewrite it ("program or binary"). From 856aa213b1e0058441ab3a29e38bcc8e1765fbc7 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:48:44 -0800 Subject: [PATCH 27/39] Add an introduction to the tooling sub-chapters --- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/tooling/index.md | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 reference-dev-guide/src/tooling/index.md diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index b7103ace10..3c586b2007 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -3,7 +3,7 @@ - [Introduction](introduction.md) - [Contribution process]() - [Publishing process](publishing.md) -- [Reference tooling]() +- [Reference tooling](tooling/index.md) - [Building the Reference](tooling/building.md) - [mdbook-spec](tooling/mdbook-spec.md) - [Tests](tests.md) diff --git a/reference-dev-guide/src/tooling/index.md b/reference-dev-guide/src/tooling/index.md new file mode 100644 index 0000000000..be8fb539ee --- /dev/null +++ b/reference-dev-guide/src/tooling/index.md @@ -0,0 +1,10 @@ +# Reference tooling + +The Reference uses [mdBook] to convert its source files from Markdown to HTML. See [Building the Reference] for more information. Additionally, there is an mdBook extension called [`mdbook-spec`] which adds a variety of custom features used by the Reference. + +In addition to the book tooling, there is a variety of testing tools documented in the [tests chapter]. + +[`mdbook-spec`]: mdbook-spec.md +[Building the Reference]: building.md +[mdbook]: https://rust-lang.github.io/mdBook/ +[tests chapter]: ../tests.md From 994b06b603f0f73a7a2c7bc747e69a1d00665c99 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:51:26 -0800 Subject: [PATCH 28/39] Add a resources chapter --- reference-dev-guide/src/SUMMARY.md | 2 +- reference-dev-guide/src/resources.md | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 reference-dev-guide/src/resources.md diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 3c586b2007..264d8bf0af 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -21,4 +21,4 @@ - [Language and grammar]() - [Punctuation](style/punctuation.md) - [Review policy](review-policy.md) -- [Resources]() +- [Resources](resources.md) diff --git a/reference-dev-guide/src/resources.md b/reference-dev-guide/src/resources.md new file mode 100644 index 0000000000..0c70c04b66 --- /dev/null +++ b/reference-dev-guide/src/resources.md @@ -0,0 +1,6 @@ +# Resources + +The Reference team has collected a set of resources about language specifications and technical writing. + +- [Language specs](https://hackmd.io/@rust-spec-team/HJey-puL6) --- It can be very useful to become familiar with how other languages are specified. This includes papers, standards, and commentary on how languages are specified. +- [Style and writing guides](https://hackmd.io/@rust-spec-team/rkj1RS3uR) --- This contains a large list of different English and technical writing guides. From 8e71ec854f819118279599422b2488e42b2c1aee Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:56:41 -0800 Subject: [PATCH 29/39] Link README to the new contributor guide --- README.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/README.md b/README.md index 893ae494d9..a06d5c10da 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,4 @@ This document is the primary reference for the Rust programming language. ## Contributor docs -There are several pages for those working on the reference: - -* [Authoring guide](https://github.com/rust-lang/reference/blob/master/docs/authoring.md): Guidelines for writing content. -* [Review policy](https://github.com/rust-lang/reference/blob/master/docs/review-policy.md): Guidelines for reviewers. -* [Grammar](https://github.com/rust-lang/reference/blob/master/docs/grammar.md): How the grammar syntax works. -* [Attribute template](https://github.com/rust-lang/reference/blob/master/docs/attribute-template.md): The standard template for documenting an attribute. - -## Running tests - -There are several different kinds of tests you can run (these are enforced on CI): - -* `mdbook test`: This will run the inline Rust codeblocks (internally it uses `rustdoc` to do this). -* `cargo xtask style-check`: This will validate some style checks (see [authoring guide](docs/authoring.md)). -* `cargo xtask linkcheck`: This will validate that markdown links aren't broken. -* `cargo xtask test-all`: Runs all tests. +See the [Reference Developer Guide](https://rust-lang.github.io/reference/reference-dev-guide/) for information on contributing to the Reference. From f4cea7a0fdb84825bc922509fabee6b69737b610 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 23 Nov 2025 07:57:24 -0800 Subject: [PATCH 30/39] Remove STYLE.md This has been superseded by the contributor guide. --- STYLE.md | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 STYLE.md diff --git a/STYLE.md b/STYLE.md deleted file mode 100644 index 5a64884615..0000000000 --- a/STYLE.md +++ /dev/null @@ -1,5 +0,0 @@ -# Rust reference style guide - -See the [Authoring Guide] for details on the style used in the reference. - -[Authoring Guide]: docs/authoring.md From bb75924da0d84f37d6dee9a21b212db199787f0c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 15:13:03 -0800 Subject: [PATCH 31/39] Add a contribution process chapter --- reference-dev-guide/src/SUMMARY.md | 3 +- reference-dev-guide/src/introduction.md | 4 - reference-dev-guide/src/process/index.md | 80 +++++++++++++++++++ .../src/process/stabilization.md | 24 ++++++ 4 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 reference-dev-guide/src/process/index.md create mode 100644 reference-dev-guide/src/process/stabilization.md diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md index 264d8bf0af..5307a723cc 100644 --- a/reference-dev-guide/src/SUMMARY.md +++ b/reference-dev-guide/src/SUMMARY.md @@ -1,7 +1,8 @@ # Summary - [Introduction](introduction.md) -- [Contribution process]() +- [Contribution process](process/index.md) + - [Stabilization process](process/stabilization.md) - [Publishing process](publishing.md) - [Reference tooling](tooling/index.md) - [Building the Reference](tooling/building.md) diff --git a/reference-dev-guide/src/introduction.md b/reference-dev-guide/src/introduction.md index 21ea155ebe..1feecf7052 100644 --- a/reference-dev-guide/src/introduction.md +++ b/reference-dev-guide/src/introduction.md @@ -30,10 +30,6 @@ Feel free to take information from the standard library and Rustonomicon as appr Note that we don't write documentation for purely library features such as threads and IO and we don't write about Rust in the future. Documentation is written as if the current stable release of Rust is the last release. The `master` branch of the Reference corresponds to what is **stable** on the `master` branch ("nightly") of [rust-lang/rust]. If you want to write about Rust in the future, you want [the Unstable book][unstable]. -## Stabilization - -When something that alters the language is stabilized, an issue should be opened on the Reference [issue tracker] to track the documentation process. This should include links to any relevant information, such as the stabilization PR, the RFC, the tracking issue, and anything else that would be helpful for writing the documentation. - [Authoring Guide]: docs/authoring.md [introduction]: https://doc.rust-lang.org/nightly/reference/introduction.html [issue tracker]: https://github.com/rust-lang/reference/issues diff --git a/reference-dev-guide/src/process/index.md b/reference-dev-guide/src/process/index.md new file mode 100644 index 0000000000..7af8391953 --- /dev/null +++ b/reference-dev-guide/src/process/index.md @@ -0,0 +1,80 @@ +# Contribution process + +## Before contributing + +We encourage people to discuss their changes before opening a PR. This gives the Reference team a chance to understand your idea better and ensure it fits with the intended direction of the Reference. Typically, you should file an issue or start a thread on [Zulip](#zulip) before submitting a pull request. + +## Contributing process overview + +The general outline of a contribution is as follows: + +1. [Check out the source.](../tooling/building.md#checking-out-the-source) +2. [Install mdbook.](../tooling/building.md#installing-mdbook) +3. [Learn to build the book locally.](../tooling/building.md#running-mdbook) +4. Make your changes to the source files. Be sure to follow all the guidelines in this book for styling, conventions, etc. +5. [Run the tests.](../tests.md) +6. [Submit a pull request](#submitting-a-pull-request) +7. The PR will go through the review process. + - There is a [guide](../review-policy.md) for the types of reviews it may undergo. + - This may take a while, as the team has limited time. +8. Once approved, a team member will merge the change. + - The team may apply editorial changes before merging. + - It may take a few weeks for the change to appear on the [nightly website](https://doc.rust-lang.org/nightly/reference/). See [the publishing chapter](../publishing.md) for more details. + +## Office hours + +The lang-docs team holds office hours on Tuesdays at [3:30 PM US/Eastern](https://dateful.com/convert/est-edt-eastern-time?t=330pm). We meet on [Jitsi Meet](https://meet.jit.si/rust-t-lang-docs). Check the [Zulip](#zulip) channel for the latest status and availability. + +## Zulip + +There are channels on Zulip for more direct discussions about the Reference: + +- [`#t-lang-docs`](https://rust-lang.zulipchat.com/#narrow/channel/237824-t-lang-docs) --- Used by the lang docs team. +- [`#t-lang-docs/reference`](https://rust-lang.zulipchat.com/#narrow/channel/520709-t-lang-docs.2Freference) --- Discussion about the Reference specifically. + +## Working on issues + +Issues labeled with [Help Wanted] are ones the team wants to see addressed and is asking for contributions. + +If you want to work on an issue, you can assign yourself by commenting `@rustbot claim`. See [issue assignment] for more information. + +[Help Wanted]: https://github.com/rust-lang/reference/issues?q=state%3Aopen%20label%3A%22Help%20Wanted%22 +[issue assignment]: https://forge.rust-lang.org/triagebot/issue-assignment.html + +## New features + +See the [stabilization chapter] for information on how to document new features. + +[stabilization chapter]: stabilization.md + +## Minor changes + +Minor changes, like small corrections, wording cleanup, or formatting fixes, can be made simply by opening a PR. + +## Major changes + +Major changes, such as large rewrites, reorganization, or new chapters, should be approved by the Reference team first. Open an issue (if there isn't already one) to discuss the kinds of changes you are interested in. If the Reference team is able, they can work with you to approve the change. + +## Submitting a pull request + +When submitting a pull request, please follow these guidelines: + +- Include a clear description of what the change is and why it is being made. +- Try to keep a clean git history, with each commit explaining the reason for the change. +- Use [GitHub’s keywords] in the description to automatically link to an issue if the PR resolves it. For example, `Closes #1234` will link issue #1234 to the PR. When the PR is merged, GitHub will automatically close the issue. + +When your PR is submitted, GitHub automatically runs all tests. The GitHub interface shows a green checkmark if it passes, or a red X if it fails. Links to the logs are available on the PR page to diagnose any issues. + +[GitHub’s keywords]: https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue + +### PR labeling + +PRs are marked with [labels] like [`S-waiting-on-review`] or [`S-waiting-on-author`] to indicate their status. Anyone can use the [`@rustbot`] bot to adjust the labels. If a PR is marked as `S-waiting-on-author` and you have pushed new changes that you would like reviewed, you can comment on the PR with `@rustbot ready`. The bot will switch the labels on the PR. + +More information about these commands can be found at the [shortcuts documentation]. + +[`@rustbot`]: https://github.com/rustbot +[`S-waiting-on-author`]: https://github.com/rust-lang/reference/labels/S-waiting-on-author +[`S-waiting-on-review`]: https://github.com/rust-lang/reference/labels/S-waiting-on-review +[labels]: https://github.com/rust-lang/reference/labels +[shortcuts documentation]: https://forge.rust-lang.org/triagebot/shortcuts.html diff --git a/reference-dev-guide/src/process/stabilization.md b/reference-dev-guide/src/process/stabilization.md new file mode 100644 index 0000000000..f70d64fe8f --- /dev/null +++ b/reference-dev-guide/src/process/stabilization.md @@ -0,0 +1,24 @@ +# Stabilization process + +New features and changes to the Rust language usually require an update to the Reference to incorporate the change. This can be done at any time before stabilization, and it is usually better to prepare a PR early (assuming the implementation is not expected to change significantly). + +An exception to this process occurs when a language change involves a section of the Reference or language that is undocumented. For example, type inference is currently not documented, so changes to it do not require an update to the Reference. + +## Pull request + +When opening a PR, please include links to as much information as possible so that reviewers can better understand the change. This includes links to the following, if they exist: + +- The tracking issue. +- The `rust-lang/rust` stabilization pull request. +- The stabilization report. +- Background information such as RFCs. +- The files in `rustc` where it is implemented, if it is isolated to a relatively concise part. +- The tests in `rust-lang/rust`. + +Some of this information may already exist, such as in the tracking issue, stabilization report, or PR, so there is no need to duplicate it. + +## Inline tests + +Because the Reference only documents stabilized features, inline tests will fail. We intend to improve this process in the future (see [#1864]). + +[#1864]: https://github.com/rust-lang/reference/issues/1864 From 5f173b3aeb95631b92ca70985c36a61a4130702f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:03:31 -0800 Subject: [PATCH 32/39] Apply some light edits to the rules chapter --- reference-dev-guide/src/rules/index.md | 26 +++++++++---------- .../src/rules/test-annotations.md | 10 +++---- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/reference-dev-guide/src/rules/index.md b/reference-dev-guide/src/rules/index.md index 5dd923de9b..ad2af6b62c 100644 --- a/reference-dev-guide/src/rules/index.md +++ b/reference-dev-guide/src/rules/index.md @@ -1,44 +1,44 @@ # Language rules -Clauses within the Reference are labeled with a named *rule*. This provides the ability to link and refer to individual clauses, and to [link to the `rustc` testsuite](test-annotations.md). +Clauses within the Reference are labeled with a named *rule*. This provides the ability to link and refer to individual clauses, and to [link to the `rustc` test suite](test-annotations.md). ## Rule labels -Most clauses should be preceded with a rule label. A rule label should be on a line by itself, and should look like this: +Most clauses should be preceded by a rule label. A rule label should be on a line by itself, and should look like this: ```markdown r[foo.bar] ``` -The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`). +The rule name should be lowercase, with periods separating components from most general to most specific (like `r[array.repeat.zero]`). -Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are [automatic link references] so that any rule can be referred to from any page in the book. +Rules can be linked to by their ID using Markdown such as `[foo.bar]`. There are [automatic link references] so that any rule can be referred to from any page in the book. -In the HTML, the rules are clickable just like headers. +In the HTML, the rules are clickable, just like headers. ## Rule guidelines -When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: +When assigning rules to new paragraphs or modifying rule names, use the following guidelines: 1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to. -2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break. +2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous one, separate it with a hard (rendered) line break. - This content will be moved to `[!NOTE]` or more specific admonitions in the future. 3. Rust code examples and tests do not need their own rules. 4. Use the following guidelines for admonitions: - Notes: Do not include a rule. - Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. - - Target specific behavior: Always include the rule. + - Target-specific behavior: Always include the rule. - Edition differences: Always include the rule. 5. The following keywords should be used to identify paragraphs when unambiguous: - - `intro`: The beginning paragraph of each section - should explain the construct being defined overall. + - `intro`: The beginning paragraph of each section. It should explain the construct being defined overall. - `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used. - - `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`). -6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows: - - If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). + - `namespace`: For items only, specifies the namespace(s) the item introduces a name in. It may also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`). +6. When a rule doesn't fall under the above keywords, or for section rule IDs, name the subrule as follows: + - If the rule names a specific Rust language construct (e.g., an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). - Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule". - Whenever possible, do not repeat previous components of the rule. - Edition differences admonitions should typically be named by the edition where the behavior changed. You should be able to correspond the dates to the chapters in . - - Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). + - Target-specific admonitions should typically be named by the least specific target property to which they apply (e.g., if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686`, and `x86_64`. If a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). - Use an appropriately descriptive, but short, name if the language does not provide one. [automatic link references]: ../links.md#rule-links diff --git a/reference-dev-guide/src/rules/test-annotations.md b/reference-dev-guide/src/rules/test-annotations.md index be01c2307d..c641c2a1fd 100644 --- a/reference-dev-guide/src/rules/test-annotations.md +++ b/reference-dev-guide/src/rules/test-annotations.md @@ -1,15 +1,15 @@ # rustc test annotations -Tests in can be linked to rules in the reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked. +Tests in can be linked to rules in the Reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked. -Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link it to a rule. The header can be specified multiple times if a single file covers multiple rules. +Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link them to a rule. The header can be specified multiple times if a single file covers multiple rules. -Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for making sure every rule has a test associated with it. +Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for ensuring every rule has a test associated with it. -The tests are beneficial for reviewers to see the behavior of a rule. It is also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names). +The tests are beneficial for reviewers to see the behavior of a rule. They are also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the Reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names). Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`. -We are not expecting 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence things are developed, and resources available. +We do not expect 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence in which things are developed and the resources available. [appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html From b137d6a0d9a97b5c3e5ee81f8b855ec8361eaec7 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:17:40 -0800 Subject: [PATCH 33/39] Apply some light edits to the publishing process --- reference-dev-guide/src/publishing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reference-dev-guide/src/publishing.md b/reference-dev-guide/src/publishing.md index 65a815dc14..26edd0f60b 100644 --- a/reference-dev-guide/src/publishing.md +++ b/reference-dev-guide/src/publishing.md @@ -1,11 +1,11 @@ # Publishing process -The process for getting the Reference content into a [Rust release](https://doc.rust-lang.org/reference/#rust-releases) and on the website is: +The process for getting the Reference content into a [Rust release](https://doc.rust-lang.org/reference/#rust-releases) and on the website is as follows: 1. Changes are merged to this repository. 2. [Triagebot](https://forge.rust-lang.org/triagebot/doc-updates.html) will automatically synchronize this repository to [rust-lang/rust]. This happens every other week. The reference is tracked in [rust-lang/rust] as a [submodule](https://github.com/rust-lang/rust/tree/master/src/doc). - - This will open a PR on [rust-lang/rust] which needs to be merged, and that can take up to several days. -3. At midnight UTC, whatever is on the default branch of [rust-lang/rust] will be a part of that nightly release, and will be published after a few hours to . -4. Following Rust's [release process](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html), every 6 weeks, nightly will be promoted to beta (), and then 6 weeks after that it will be promoted to stable (). + - This will open a PR on [rust-lang/rust] that needs to be merged, which can take up to several days. +3. At midnight UTC, whatever is on the default branch of [rust-lang/rust] will be part of that nightly release and will be published after a few hours to . +4. Following Rust's [release process](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html), every 6 weeks, nightly is promoted to beta (), and 6 weeks after that, it is promoted to stable (). [rust-lang/rust]: https://github.com/rust-lang/rust/ From 0e23db78fc48bacba704b2645fd37a636048ddad Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:32:43 -0800 Subject: [PATCH 34/39] Apply light edits to standard library links --- reference-dev-guide/src/links.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference-dev-guide/src/links.md b/reference-dev-guide/src/links.md index d1629db41b..d977e19b7f 100644 --- a/reference-dev-guide/src/links.md +++ b/reference-dev-guide/src/links.md @@ -20,7 +20,7 @@ Definition link: [namespace kinds] ## Standard library links -You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: +You should link to the standard library without specifying a URL, in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: We can link to the page on `Option`: @@ -52,16 +52,16 @@ Explicit namespace disambiguation is also supported: [`std::vec`](mod@std::vec) ``` -Beware there are some limitations, for example: +Beware of some limitations, for example: -- Links to rexports from `std_arch` don't work due to . +- Links to re-exports from `std_arch` don't work due to . - Links to keywords aren't supported. -- Links to trait impls where the trait is not in the prelude doesn't work. Traits must be in scope, and there currently isn't a way to add those. +- Links to trait impls where the trait is not in the prelude don't work. Traits must be in scope, and currently there is no way to add them. - If there are multiple generic implementations, it will link to one randomly (see ). When running into a rustdoc limitation, consider manually linking to the correct page using a relative link. For example, `../std/arch/macro.is_x86_feature_detected.html`. -When rendering the Reference locally, by default it uses relative links to conform with how the books are published. This probably isn't what you want, so you usually will want to set the [`SPEC_RELATIVE=0` environment variable][rel] so that the links go to the live site instead. +When rendering the Reference locally, it uses relative links by default to conform with how the books are published. This probably isn't what you want, so you will usually want to set the [`SPEC_RELATIVE=0` environment variable][rel] so that the links go to the live site instead. [intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html [rel]: tooling/building.md#spec_relative From 012093294d9f9f937514b515c3a5a27018a15711 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:34:45 -0800 Subject: [PATCH 35/39] Apply some light edits to the introduction This introduction should probably receive deeper edits to make it fit into the guide better. --- reference-dev-guide/src/introduction.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference-dev-guide/src/introduction.md b/reference-dev-guide/src/introduction.md index 1feecf7052..8190842eb1 100644 --- a/reference-dev-guide/src/introduction.md +++ b/reference-dev-guide/src/introduction.md @@ -8,7 +8,7 @@ It is encouraged for you to read the [introduction] of the Reference to familiar ## Critiquing the Reference -This is the easiest way to contribute. Basically, as you read the Reference, if you find something confusing, incorrect, or missing, then you can file an issue against the Reference explaining your concerns. +This is the easiest way to contribute. As you read the Reference, if you find something confusing, incorrect, or missing, then you can file an issue against the Reference explaining your concerns. ## Editing the Reference @@ -16,19 +16,19 @@ Typos and incorrect links get through from time to time. Should you find them, w ## Adding examples and glossary entries -Examples are great. Many people will only read examples and ignore the prose. Ideally, every facet of every feature will have an example. +Examples are great. Many people will only read examples and ignore the prose. Ideally, every facet of every feature should have an example. -Likewise, the Reference has a glossary. It doesn't need to explain every facet of every feature nor contain every definition, but it does need to be expanded upon. Ideally entries in the glossary link to the associated documentation. +Likewise, the Reference has a glossary. It doesn't need to explain every facet of every feature nor contain every definition, but it does need to be expanded upon. Ideally, entries in the glossary should link to the associated documentation. ## Adding documentation -There are a lot of features that are not documented at all or are documented poorly. This is the hardest, but definitely most valuable. Pick an unassigned issue from the [issue tracker], and write about it. +There are a lot of features that are not documented at all or are documented poorly. This is the hardest task, but definitely the most valuable. Pick an unassigned issue from the [issue tracker], and write about it. While writing, you may find it handy to have a [playground] open to test out what you are documenting. Feel free to take information from the standard library and Rustonomicon as appropriate. -Note that we don't write documentation for purely library features such as threads and IO and we don't write about Rust in the future. Documentation is written as if the current stable release of Rust is the last release. The `master` branch of the Reference corresponds to what is **stable** on the `master` branch ("nightly") of [rust-lang/rust]. If you want to write about Rust in the future, you want [the Unstable book][unstable]. +Note that we don't write documentation for purely library features, such as threads and IO, and we don't write about Rust in the future. Documentation is written as if the current stable release of Rust is the last release. The `master` branch of the Reference corresponds to what is **stable** on the `master` branch ("nightly") of [rust-lang/rust]. If you want to write about Rust in the future, you want [the Unstable book][unstable]. [Authoring Guide]: docs/authoring.md [introduction]: https://doc.rust-lang.org/nightly/reference/introduction.html From 8bfc8b9ef448782b99b09e5a0f40dd41b57daa26 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:37:46 -0800 Subject: [PATCH 36/39] Apply some light edits to the grammar chapter --- reference-dev-guide/src/grammar.md | 40 +++++++++++++++--------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/reference-dev-guide/src/grammar.md b/reference-dev-guide/src/grammar.md index 2b05ec3e3a..bc6fbb58aa 100644 --- a/reference-dev-guide/src/grammar.md +++ b/reference-dev-guide/src/grammar.md @@ -1,8 +1,8 @@ # Rust grammar -The Reference grammar is written in markdown code blocks using a modified BNF-like syntax (with a blend of regex and other arbitrary things). The [`mdbook-spec`] extension parses these rules and converts them to a renderable format, including railroad diagrams. +The Reference grammar is written in markdown code blocks using a modified BNF-like syntax (with a blend of regex and other arbitrary things). The [`mdbook-spec`] extension parses these rules and converts them into a renderable format, including railroad diagrams. -The code block should have a lang string with the word "grammar", a comma, and the category of the grammar, like this: +The code block should have a lang string with the word `grammar`, a comma, and the category of the grammar, like this: ~~~ ```grammar,items @@ -14,7 +14,7 @@ The category is used to group similar productions on the grammar summary page in ## Grammar syntax -The syntax for the grammar itself is pretty close to what is described in the [Notation chapter], though there are some rendering differences. +The syntax for the grammar itself is similar to what is described in the [Notation chapter], though there are some rendering differences. A "root" production, marked with `@root`, is one that is not used in any other production. @@ -94,38 +94,38 @@ Group -> `(` ` `* Expression ` `* `)` NegativeExpression -> `~` ( Charset | Terminal | NonTerminal ) ``` -The general format is a series of productions separated by blank lines. The expressions are: +The general format is a series of productions separated by blank lines. The expressions are as follows: | Expression | Example | Description | |------------|---------|-------------| -| Unicode | U+0060 | A single unicode character. | +| Unicode | U+0060 | A single Unicode character. | | NonTerminal | FunctionParameters | A reference to another production by name. | -| Break | | This is used internally by the renderer to detect line breaks and indentation. | +| Break | | Used internally by the renderer to detect line breaks and indentation. | | Comment | // Single line comment. | A comment extending to the end of the line. | -| Terminal | \`example\` | This is a sequence of exact characters, surrounded by backticks | -| Charset | [ \`A\`-\`Z\` \`0\`-\`9\` \`_\` ] | A choice from a set of characters, space separated. There are three different forms. | -| CharacterRange | [ \`A\`-\`Z\` ] | A range of characters, each character should be in backticks. -| CharacterTerminal | [ \`x\` ] | A single character, surrounded by backticks. | -| CharacterName | [ LF ] | A nonterminal, referring to another production. | -| Prose | \ | This is an English description of what should be matched, surrounded in angle brackets. | -| Group | (\`,\` Parameter)+ | This groups an expression for the purpose of precedence, such as applying a repetition operator to a sequence of other expressions. -| NegativeExpression | ~[\` \` LF] | Matches anything except the given Charset, Terminal, or Nonterminal. | -| Sequence | \`fn\` Name Parameters | A sequence of expressions, where they must match in order. | +| Terminal | \`example\` | A sequence of exact characters, surrounded by backticks. | +| Charset | \[ \`A\`-\`Z\` \`0\`-\`9\` \`_\` \] | A choice from a set of characters, space-separated. There are three different forms. | +| CharacterRange | \[ \`A\`-\`Z\` \] | A range of characters; each character should be in backticks. +| CharacterTerminal | \[ \`x\` \] | A single character, surrounded by backticks. | +| CharacterName | \[ LF \] | A nonterminal, referring to another production. | +| Prose | \ | An English description of what should be matched, surrounded in angle brackets. | +| Group | (\`,\` Parameter)+ | Groups an expression for the purpose of precedence, such as applying a repetition operator to a sequence of other expressions. +| NegativeExpression | ~\[\` \` LF\] | Matches anything except the given Charset, Terminal, or Nonterminal. | +| Sequence | \`fn\` Name Parameters | A sequence of expressions that must match in order. | | Alternation | Expr1 \| Expr2 | Matches only one of the given expressions, separated by the vertical pipe character. | -| Suffix | \_except \[LazyBooleanExpression\]\_ | This adds a suffix to the previous expression to provide an additional English description to it, rendered in subscript. This can have limited markdown, but try to avoid anything except basics like links. | -| Footnote | \[^extern-safe\] | This adds a footnote, which can supply some extra information that may be helpful to the user. The footnote itself should be defined outside of the code block like a normal markdown footnote. | +| Suffix | \_except \[LazyBooleanExpression\]\_ | Adds a suffix to the previous expression to provide an additional English description, rendered in subscript. This can contain limited markdown, but try to avoid anything except basics like links. | +| Footnote | \[^extern-safe\] | Adds a footnote, which can supply extra information that may be helpful to the user. The footnote itself should be defined outside of the code block like a normal markdown footnote. | | Optional | Expr? | The preceding expression is optional. | | Repeat | Expr* | The preceding expression is repeated 0 or more times. | | Repeat (non-greedy) | Expr*? | The preceding expression is repeated 0 or more times without being greedy. | | RepeatPlus | Expr+ | The preceding expression is repeated 1 or more times. | | RepeatPlus (non-greedy) | Expr+? | The preceding expression is repeated 1 or more times without being greedy. | -| RepeatRange | Expr{2..4} | The preceding expression is repeated between the range of times specified. Either bounds can be excluded, which works just like Rust ranges. | +| RepeatRange | Expr{2..4} | The preceding expression is repeated between the range of times specified. Either bound can be excluded, which works just like Rust ranges. | ## Automatic linking -The [`mdbook-spec`] plugin automatically adds markdown link definitions for all the production names on every page. If you want to link directly to a production name, all you need to do is surround it in square brackets, like `[ArrayExpression]`. +The [`mdbook-spec`] plugin automatically adds markdown link definitions for all production names on every page. To link directly to a production name, simply surround it in square brackets, like `[ArrayExpression]`. -In some cases there might be name collisions with the automatic linking of rule names. In that case, disambiguate with the `grammar-` prefix, such as `[Type][grammar-Type]`. You can also do that if you just feel like being more explicit. +In some cases, there might be name collisions with the automatic linking of rule names. In that case, disambiguate with the `grammar-` prefix, such as `[Type][grammar-Type]`. You can also do this if you prefer to be more explicit. [`mdbook-spec`]: tooling/mdbook-spec.md [Notation chapter]: https://doc.rust-lang.org/nightly/reference/notation.html From b321e4f212e4581c817a5043410070dbc0f4c422 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:39:51 -0800 Subject: [PATCH 37/39] Apply some light edits to the markdown chapter --- reference-dev-guide/src/formatting/markdown.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/reference-dev-guide/src/formatting/markdown.md b/reference-dev-guide/src/formatting/markdown.md index 3ae9d78d13..aa42bd1946 100644 --- a/reference-dev-guide/src/formatting/markdown.md +++ b/reference-dev-guide/src/formatting/markdown.md @@ -5,27 +5,27 @@ There are automated checks for some of these rules. Run [`cargo xtask style-chec ## Formatting style - Use [ATX-style headings][atx] (not Setext) with [sentence case]. -- Do not use tabs, only spaces. +- Do not use tabs; use only spaces. - Files must end with a newline. -- Lines must not end with spaces. Double spaces have semantic meaning, but can be invisible. Use a trailing backslash if you need a hard line break. +- Lines must not end with spaces. Double spaces have semantic meaning but can be invisible. Use a trailing backslash if you need a hard line break. - If possible, avoid double blank lines. - Do not wrap long lines. This helps with reviewing diffs of the source. -- Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. +- Use [smart punctuation] instead of Unicode characters. For example, use `---` for an em-dash instead of the Unicode character. Characters like the em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. - See the [admonitions chapter] for formatting callouts such as notes, edition differences, and warnings. ## Code blocks -- Do not use indented code blocks; use 3+ backticks code blocks instead. +- Do not use indented code blocks; use fenced code blocks with 3+ backticks instead. - Code blocks should have an explicit language tag. ## Links See the [links chapter] for more information about linking. -- Links to other chapters should be relative with the `.md` extension. +- Links to other chapters should be relative and use the `.md` extension. - Links to other rust-lang books that are published with the Reference should also be relative so that the linkchecker can validate them. See [outside book links]. -- Links to the standard library should use rustdoc-style links described in [standard library links]. -- The use of reference links is preferred, with shortcuts if appropriate. Place the sorted link reference definitions at the bottom of the file or at the bottom of a section if there are an unusually large number of links that are specific to the section. +- Links to the standard library should use rustdoc-style links as described in [standard library links]. +- The use of reference links is preferred, with shortcuts if appropriate. Place sorted link reference definitions at the bottom of the file, or at the bottom of a section if there is an unusually large number of links specific to that section. ```markdown Example of shortcut link: [enumerations] From 19cef878456f32fd745fb067b70d80846cef431c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:43:22 -0800 Subject: [PATCH 38/39] Apply some light edits to the examples chapter --- reference-dev-guide/src/examples.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/reference-dev-guide/src/examples.md b/reference-dev-guide/src/examples.md index 19bdd0f77a..6c31f7063a 100644 --- a/reference-dev-guide/src/examples.md +++ b/reference-dev-guide/src/examples.md @@ -12,24 +12,24 @@ See the [mdBook supported languages] for a list of supported languages. ## rustdoc attributes -Rust examples are [tested via rustdoc], and should include the appropriate annotations: +Rust examples are [tested via rustdoc] and should include the appropriate annotations: -- `edition2015`, `edition2018`, etc. --- If it is edition-specific (see `book.toml` for the default). -- `no_run` --- The example should compile successfully, but should not be executed. -- `should_panic` --- The example should compile and run, but produce a panic. +- `edition2015`, `edition2018`, etc. --- Use if it is edition-specific (see `book.toml` for the default). +- `no_run` --- The example should compile successfully but should not be executed. +- `should_panic` --- The example should compile and run but produce a panic. - `compile_fail` --- The example is expected to fail to compile. -- `ignore` --- The example shouldn't be built or tested. This should be avoided if possible. Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. An HTML comment such as `` should be placed before the example to explain why it is ignored. -- `Exxxx` --- If the example is expected to fail to compile with a specific error code, include that code so that rustdoc will check that the expected code is used. +- `ignore` --- The example shouldn't be built or tested. This should be avoided if possible. Usually, this is only necessary when the testing framework does not support it (such as external crates, modules, or a proc-macro) or when it contains pseudo-code that is not valid Rust. An HTML comment, such as ``, should be placed before the example to explain why it is ignored. +- `Exxxx` --- If the example is expected to fail to compile with a specific error code, include that code so that `rustdoc` checks that the expected code is used. See the [rustdoc documentation] for more detail. ## Combining examples -When demonstrating success cases, many such cases may be included in a single code block. For failure cases, however, each example must appear in a separate code block so that the tests can ensure that each case indeed fails and fails with the appropriate error code or codes. +When demonstrating success cases, multiple cases may be included in a single code block. For failure cases, however, each example must appear in a separate code block so that the tests can ensure that each case indeed fails with the appropriate error code. ## Testing examples -The Rust code blocks are tested in CI. You can verify the samples pass by running [`mdbook test`]. +The Rust code blocks are tested in CI. You can verify that the samples pass by running [`mdbook test`]. [`mdbook test`]: tests.md#inline-tests [mdBook supported languages]: https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting.html#supported-languages From a7a2033fa65ec2b8cfe096ff58e9fbb62ada696e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Nov 2025 17:50:14 -0800 Subject: [PATCH 39/39] Apply light edits to the attributes chapter --- reference-dev-guide/src/attributes.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/reference-dev-guide/src/attributes.md b/reference-dev-guide/src/attributes.md index 4f886dbc1e..02fec36d0e 100644 --- a/reference-dev-guide/src/attributes.md +++ b/reference-dev-guide/src/attributes.md @@ -2,7 +2,7 @@ Attributes should use the following template. Examples are given for phrasing you *should* use, but you should deviate if the attribute doesn't fit any of the examples or if they get in the way of clarity. -When an attribute (or a new attribute position in the grammar) is added, be sure to update all the "attributes on" sections which list which attributes can be used in various positions. +When an attribute (or a new attribute position in the grammar) is added, be sure to update all the "attributes on" sections that list which attributes can be used in various positions. ---- @@ -11,7 +11,7 @@ r[PARENT.example] ## The `example` attribute r[PARENT.example.intro] -The *`example` [attribute][attributes]* ...give a high level description. +The *`example` [attribute][attributes]* ...give a high-level description. > [!EXAMPLE] > ```rust @@ -22,7 +22,7 @@ The *`example` [attribute][attributes]* ...give a high level description. > ``` r[PARENT.example.syntax] -Describe the accepted syntax of this attribute. You can either explain that it uses one of the pre-existing grammars like `MetaWord` or define an explicit grammar. If there are different forms, briefly describe the syntax here, and link to the appropriate rules below that explain the behavior of the different forms. Examples: +Describe the accepted syntax of this attribute. You can either explain that it uses one of the pre-existing grammars, like `MetaWord`, or define an explicit grammar. If there are different forms, briefly describe the syntax here and link to the appropriate rules below that explain the behavior of the different forms. Examples: ---- @@ -50,7 +50,7 @@ The `example` attribute uses the [MetaNameValueStr] syntax. The value in the str ---- -The `example` attribute has these forms: +The `example` attribute has the following forms: - [MetaWord] > [!EXAMPLE] @@ -92,7 +92,7 @@ The [MetaNameValueStr] form of the `example` attribute provides a way to specify > ``` r[PARENT.example.allowed-positions] -Explain the valid positions where this attribute may be used. +Explain the valid positions where this attribute can be used. See [`check_attr`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_passes/src/check_attr.rs) and [`builtin_attrs.rs`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_feature/src/builtin_attrs.rs) in the compiler. Don't forget that some attributes only work as inner or outer attributes. Examples: @@ -110,7 +110,7 @@ The `example` attribute is allowed anywhere attributes are allowed. ---- -If there are unused attribute warnings, or if rustc is incorrectly accepting some positions, include a note about these. +If there are unused attribute warnings, or if `rustc` is incorrectly accepting some positions, include a note about these. > [!NOTE] > `rustc` ignores use in other positions but lints against it. This may become an error in the future. @@ -118,7 +118,7 @@ If there are unused attribute warnings, or if rustc is incorrectly accepting som ---- r[PARENT.example.duplicates] -Explain the behavior if the attribute is specified multiple times on an element. See [`AttributeDuplicates`](https://github.com/rust-lang/rust/blob/40d2563ea200f9327a8cb8b99a0fb82f75a7365c/compiler/rustc_feature/src/builtin_attrs.rs#L143) in the compiler. Examples: +Explain the behavior when the attribute is specified multiple times on an element. See [`AttributeDuplicates`](https://github.com/rust-lang/rust/blob/40d2563ea200f9327a8cb8b99a0fb82f75a7365c/compiler/rustc_feature/src/builtin_attrs.rs#L143) in the compiler. Examples: ---- @@ -160,7 +160,7 @@ If the `example` attribute is used more than once on an item, then the combinati ---- r[PARENT.example.ATTR_NAME] -If this attribute cannot be used with another attribute, specify each one. Do this on both attributes. Example: +If this attribute cannot be used with another attribute, specify each conflicting attribute. Do this for both attributes. Example: ---- @@ -169,7 +169,7 @@ The `example` attribute may not be used with the [`foo`] attribute. ---- r[PARENT.example.unsafe] -If this is an `unsafe` attribute, explain the safety conditions it must uphold. If not, don't include this section. Be sure to also update `attributes.safety` when adding a new unsafe attribute. Example: +If this is an `unsafe` attribute, explain the safety conditions it must uphold. Otherwise, do not include this section. Be sure to also update `attributes.safety` when adding a new unsafe attribute. Example: ---- @@ -178,7 +178,7 @@ The `example` attribute must be marked with [`unsafe`][attributes.safety] becaus ---- r[PARENT.example.stdlib] -This rule explains if the attribute is exported in the standard library. Skip this if it is not. Example: +This rule explains whether the attribute is exported in the standard library. Skip this section if it is not. Example: ---- @@ -187,4 +187,4 @@ The `example` attribute is exported in the standard library prelude as [`core::p ---- r[PARENT.example.foo] -From here on, add rules explaining all the behaviors of the attribute. If the attribute is very simple, you can just have one rule called ".behavior" to explain its behavior. More complex attributes, such as those with multiple kinds of inputs or different modes should describe each as a separate rule. +From here on, add rules explaining all the behaviors of the attribute. If the attribute is very simple, you can just have one rule called `.behavior` to explain its behavior. More complex attributes, such as those with multiple kinds of inputs or different modes, should describe each as a separate rule.