Introduction

Thank you for your interest in contributing to The Rust Reference. This document 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.

We encourage 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. 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.

Adding examples and glossary entries

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 everything or contain every possible definition, but it does need to be expanded upon from its current state. 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 most valuable task. 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 main branch (“nightly”) of rust-lang/rust. If you want to write about Rust in the future, you want The Unstable Book.

Contribution process

Before contributing

For nontrivial changes, we encourage people to discuss these 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 before submitting a pull request.

Contributing process overview

The general outline of a contribution is as follows:

1. Check out the source.
2. Install mdbook.
3. Learn to build the book locally.
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.
6. Submit a pull request
7. The PR will go through the review process.
   • See Review Policy 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. See Publishing for more details.

Office hours

The lang-docs team holds office hours on Tuesdays at 3:30 PM US/Eastern. We meet on Jitsi Meet. Check the Zulip channel for the latest status and availability.

Zulip

There are channels on Zulip for discussions about the Reference:

• #t-lang-docs — Used by the lang docs team.
• #t-lang-docs/reference — Discussion about the Reference specifically.

Working on issues

When an issue is labeled with Help Wanted, the team is asking for contributions to help address it.

If you want to work on an issue, you can assign yourself by commenting @rustbot claim. See Issue Assignment for more information.

New features

See Stabilization for information on how to document new features.

Minor changes

Minor changes — such as small corrections, wording cleanup, and formatting fixes — can be made simply by opening a PR.

Major changes

Major changes — such as large rewrites, reorganizations, and new chapters — should be discussed with and 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. When the Reference team is able, they will work with you to approve or give feedback on 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.
• Keep a clean git history; each commit should explain 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, saying 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 these pass or a red X if they fail. Links to the logs are available on the PR page to diagnose any issues.

PR labeling

PRs are marked with labels such as S-waiting-on-review and 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.

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 part of the language that is undocumented or a section of the Reference that is incomplete. For example, type inference is currently not documented, so changes to the details of type inference do not require an update to the Reference.

However, when a new feature introduces a rule that can be stated independently of the undocumented material, that rule should still be documented. In this case, add the new rule to the relevant placeholder section. When the section is eventually filled out, the rule will be incorporated into the complete text.

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.

Always link to the tracking issue and, if applicable, the stabilization PR. Beyond those, information that already appears in the tracking issue, stabilization report, or PR does need to be duplicated in the PR description.

Inline tests

If a PR documents a newly stabilized feature, its inline tests will fail until the stabilization PR is merged and a new nightly compiler is available. We intend to improve this process in the future (see #1864).

Publishing process

The process for getting the Reference content into a Rust release and on the website is as follows:

1. Changes are merged to this repository.
2. Triagebot 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.

• 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 https://doc.rust-lang.org/nightly/reference/.
4. Following Rust’s release process, every 6 weeks, nightly is promoted to beta (https://doc.rust-lang.org/beta/reference/), and 6 weeks after that, it is promoted to stable (https://doc.rust-lang.org/stable/reference/).

Reference tooling

The Reference uses mdBook to convert its source files from Markdown to HTML. See Building the Reference for more information. The mdbook-spec extension adds several custom features used by the Reference.

For testing, see Running Tests.

Building the Reference

Checking out the source

To build the Reference, first clone the project:

git clone https://github.com/rust-lang/reference.git
cd reference

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 to run the tests:

rustup toolchain install nightly
rustup override set nightly

Now, ensure you have mdbook installed, as this is needed to build the Reference:

cargo install --locked mdbook

Running mdbook

mdbook provides several commands and options to help you work on the book:

• 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 https://rust-lang.github.io/mdBook/ for more information.

SPEC_RELATIVE

The SPEC_RELATIVE=0 environment variable makes links to the standard library go to https://doc.rust-lang.org/ instead of being relative. This is useful when viewing locally since you normally don’t have a copy of the standard library.

SPEC_RELATIVE=0 mdbook serve --open

The published site at https://doc.rust-lang.org/reference/ (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 https://doc.rust-lang.org/1.81.0/reference/ will stay within the 1.81.0 directory).

SPEC_DENY_WARNINGS

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.

SPEC_DENY_WARNINGS=1 mdbook serve --open

SPEC_RUST_ROOT

The SPEC_RUST_ROOT environment variable can be used to point to the directory of a checkout of https://github.com/rust-lang/rust. 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.

SPEC_RUST_ROOT=/path/to/rust mdbook serve --open

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 Building the Reference:

• 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.

Running tests

There are several different kinds of tests you can run (these are enforced in CI):

• cargo xtask test-all — Runs all tests.
• mdbook test — Tests the inline Rust code blocks.
• cargo xtask linkcheck — Validates that Markdown links aren’t broken.
• cargo xtask style-check — Validates various style checks.
• Code formatting — Checks that all Rust tooling code is formatted.
• mdbook-spec tests — Internal tests for mdbook-spec.

All tests

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 tools/xtask/src/main.rs for details on what this does.

Inline tests

mdbook test

This command runs all tests that are inline in the Markdown. Internally, this uses 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 Examples for more.

Linkcheck

cargo xtask linkcheck

This command verifies that links are not broken. It downloads and uses the 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

cargo xtask style-check

This uses the style-check tool to enforce various formatting rules.

Code formatting

CI uses cargo fmt --check to verify that all Rust sources for the tools (such as mdbook-spec) are properly formatted. All code must be formatted with rustfmt.

mdbook-spec tests

cargo test --manifest-path mdbook-spec/Cargo.toml

CI runs cargo test on mdbook-spec to execute any tests for the tool itself.

Formatting

The following chapters detail how the Reference source should be formatted.

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 (not Setext) with sentence case.
• 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.
• 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 an em dash instead of the Unicode character. Characters such as 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 Admonitions for formatting callouts such as notes, edition differences, and warnings.

Code blocks

• Do not use indented code blocks; use fenced code blocks with 3+ backticks instead.
• Code blocks should have an explicit language tag.

Links

See Links for more information about linking.

• 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 as described in standard library links.

• Prefer reference links, with shortcut reference links where 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.

  Example of shortcut link: [enumerations]
  Example of reference link with label: [block expression][block]
  
  [block]: expressions/block-expr.md
  [enumerations]: types/enum.md
  

Admonitions

mdbook-spec provides admonitions that use a style similar to GitHub-flavored Markdown. The style name is placed at the beginning of a blockquote, such as:

> [!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 are defined in theme/reference.css and the transformation and icons are in tools/mdbook-spec/src/admonitions.rs.

See Conventions in the Reference introduction for a description of how these should be used.

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 test suite.

Rule labels

Most clauses should be preceded by a rule label. A rule label should be on a line by itself and should look like this:

r[foo.bar]

The rule name should be lowercase, with periods separating components from most general to most specific (e.g., 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 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 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.
   • 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. 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. 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 https://doc.rust-lang.org/edition-guide/.
   • 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.

rustc test annotations

Tests in https://github.com/rust-lang/rust can be linked to rules in the Reference. The rule will include a link to the tests, and there is also an appendix that tracks how the rules are currently linked.

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 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. 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).

Always annotate with the most specific rule name available. For example, use asm.rules.reg-not-input rather than the broader asm.rules.

Complete coverage is the goal but is not yet expected.

Examples

Example code blocks

Code examples should use code blocks with triple backticks. The language should always be specified (such as rust).

#![allow(unused)]
fn main() {
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. — 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, modules, or a proc-macro) or when it contains pseudocode that is not valid Rust. An HTML comment, such as <!-- ignore: requires extern crate -->, 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, 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 that the samples pass by running mdbook test.

Links

This chapter explains how links should be handled by the Reference. Several of these capabilities are provided by mdbook-spec.

See also the linkchecker tests for testing links.

Rule links

Rules 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.

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. Some examples:

We can link to the page on Option:

[`std::option::Option`]

In these links, generics are ignored and can be included:

[`std::option::Option<T>`]

If we don’t want the full path in the text, we can write:

[`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:

[`alloc::vec!`]

Explicit namespace disambiguation is also supported:

[`std::vec`](mod@std::vec)

Beware of some limitations, for example:

• Links to reexports from std_arch don’t work due to https://github.com/rust-lang/rust/issues/96506.
• Links to keywords aren’t supported.
• 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 https://github.com/rust-lang/rust/issues/76895).

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, 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 so that the links go to the live site instead.

Grammar links

Link definitions are automatically generated for all grammar production names. See grammar automatic linking for more.

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:

See [`-C panic`].

[`-C panic`]: ../rustc/codegen-options/index.html#panic

Internal links

When possible, internal links should use rule links or grammar links. Otherwise, links should be relative to the file path and use the .md extension.

- Rule link: [language prelude][names.preludes.lang]
- Grammar link: [MetaWord]
- Internal link: [Modules](items/modules.md#attributes-on-modules)

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 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:

```grammar,items
ProductionName -> SomeExpression
```

The category is used to group similar productions on the grammar summary page in the appendix.

Grammar syntax

The syntax for the grammar itself is similar to what is described in Notation, though there are some rendering differences.

A “root” production, marked with @root, is one that is not used in any other production.

The syntax for the grammar notation, described here using its own notation, is:

Grammar -> Production+

BACKTICK -> U+0060

LF -> U+000A

Production ->
    ( Comment LF )*
    `@root`? Name ` ->` Expression

Name -> <Alphanumeric or `_`>+

Expression -> Sequence (` `* `|` ` `* Sequence)*

Sequence -> (` `* AdornedExpr)+

AdornedExpr -> ExprRepeat Suffix? Footnote?

Suffix -> ` _` <not underscore, unless in backtick>* `_`

Footnote -> `[^` ~[`]` LF]+ `]`

ExprRepeat ->
      Expr1 `?`
    | Expr1 `*?`
    | Expr1 `*`
    | Expr1 `+?`
    | Expr1 `+`
    | Expr1 `{` Range? `..` Range? `}`

Range -> [0-9]+

Expr1 ->
      Unicode
    | NonTerminal
    | Break
    | Comment
    | Terminal
    | Charset
    | Prose
    | Group
    | NegativeExpression

Unicode -> `U+` [`A`-`Z` `0`-`9`]4..4

NonTerminal -> Name

Break -> LF ` `+

Comment -> `//` ~[LF]+

Terminal -> BACKTICK ~[LF]+ BACKTICK

Charset -> `[` (` `* Characters)+ ` `* `]`

Characters ->
      CharacterRange
    | CharacterTerminal
    | CharacterName

CharacterRange -> BACKTICK <any char> BACKTICK `-` BACKTICK <any char> BACKTICK

CharacterTerminal -> Terminal

CharacterName -> Name

Prose -> `<` ~[`>` LF]+ `>`

Group -> `(` ` `* Expression ` `* `)`

NegativeExpression -> `~` ( Charset | Terminal | NonTerminal )

The general format is a series of productions separated by blank lines. The expressions are as follows:

Automatic linking

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]. The prefix can also be used when explicitness would aid clarity.

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 the examples 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 that list which attributes can be used in various positions.

r[PARENT.example]

The example attribute

r[PARENT.example.intro] The example [attribute][attributes] …give a high-level description.

[!EXAMPLE]

#![allow(unused)]
fn main() {
// This should be a very basic example showing the attribute
// used in some way.
#[example]
fn some_meaningful_name() {}
}

r[PARENT.example.syntax] Describe the accepted syntax of this attribute. You can either explain that it uses one of the pre-existing grammars, such as 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:

The example attribute uses the [MetaWord] syntax.

The example attribute uses the [MetaListPaths] syntax to specify a list of …

The example attribute uses the [MetaWord] and [MetaNameValueStr] syntaxes.

The example attribute uses the [MetaWord], [MetaListPaths], and [MetaNameValueStr] syntaxes.

The example attribute uses the [MetaNameValueStr] syntax. Accepted values are "X" and "Y".

The example attribute uses the [MetaNameValueStr] syntax. The value in the string must be …

The example attribute has the following forms:

• [MetaWord]

  [!EXAMPLE]

  #![allow(unused)]
  fn main() {
  #[example]
  fn f() {}
  }

• [MetaNameValueStr] — The given string must …

  [!EXAMPLE]

  #![allow(unused)]
  fn main() {
  #[example = "example"]
  fn f() {}
  }

• [MetaListNameValueStr] — As with the [MetaNameValueStr] syntax, the given string must …

  [!EXAMPLE]

  #![allow(unused)]
  fn main() {
  #[example(inner = "example")]
  fn f() {}
  }

The syntax for the example attribute is:

@root ExampleAttribute -> `example` `(` ... `)`

r[PARENT.example.syntax.foo] The [MetaNameValueStr] form of the example attribute provides a way to specify the foo.

[!EXAMPLE]

#![allow(unused)]
fn main() {
#[example = "example"]
fn some_meaningful_name() {}
}

r[PARENT.example.allowed-positions] Explain the valid positions where this attribute can be used.

See check_attr and builtin_attrs.rs in the compiler. Don’t forget that some attributes only work as inner or outer attributes. Examples:

The example attribute may only be applied to …

The example attribute may only be applied to the crate root.

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.

Note

rustc ignores use in other positions but lints against it. This may become an error in the future.

r[PARENT.example.duplicates] Explain the behavior when the attribute is specified multiple times on an element. See AttributeDuplicates in the compiler. Examples:

The example attribute may be used any number of times on a form.

Using example more than once on a form has the same effect as using it once.

The example attribute may be used only once on …

Only the first use of example on an item has effect.

Note

rustc lints against any use following the first. This may become an error in the future.

Note

rustc lints against any use following the first with a future-compatibility warning. This may become an error in the future.

Only the last use of example on an item has effect.

Note

rustc lints against any use preceding the last. This may become an error in the future.

Only the last use of example on an item is used to …

If the example attribute is used more than once on an item, then the combination of all the specified values is used as …explain how they are merged.

r[PARENT.example.ATTR_NAME] If this attribute cannot be used with another attribute, specify each conflicting attribute. Do this for both attributes. Example:

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. Otherwise, do not include this section. Be sure to also update attributes.safety when adding a new unsafe attribute. Example:

The example attribute must be marked with [unsafe][attributes.safety] because …

r[PARENT.example.stdlib] This rule explains whether the attribute is exported in the standard library. Skip this section if it is not. Example:

The example attribute is exported in the standard library prelude as [core::prelude::v1::example].

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.

Style guide

The following sections describe the preferred style for English prose in the Reference.

Wording

Use American English spelling.

Avoid qualifying something as “in Rust”; the entire Reference is about Rust.

Punctuation

Use Oxford commas.

Avoid slashes for alternatives (“program/binary”); use a conjunction or rewrite the phrase (“program or binary”).

Review policy

Team members have permission to merge changes from other contributors in the https://github.com/rust-lang/reference 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: Prose 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. 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 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 Reference, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence in the correctness of the changes, if the reviewer is well-versed in the topic, or if the relevant experts are already the author of or actively involved in the PR. It is up to the reviewer to use good judgment on when to consult.

Content should always follow the guidelines in this contributor guide.

Minor content changes

For minor content changes — such as small cleanups, wording fixes, or formatting corrections — a maintainer may push fixes directly to the PR branch and merge, without consulting the author or other reviewers.

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.

Review process flowchart

When reviewing a pull request, ask yourself the following questions:

Are the proposed changes true?

If we’re not sure and can’t easily verify it ourselves, we ask someone who would know.

Does this make any new guarantees about the language?

If this would make a new guarantee about the language, this needs to go through the lang team to be accepted (unless the lang team has clearly accepted this guarantee elsewhere). Ask @traviscross if at all unsure about any of these.

Would we have added this to the Reference ourselves?

There are a number of PRs that might be true, but when we look at them, we think to ourselves, in our heart of hearts, that this just isn’t something we would have bothered to write ourselves. We don’t want to accept a PR just because it’s in front of us and not obviously false. It should clearly add value.

Is this editorially sound?

Some PRs try to “sell” the language too much, or try to explain more (or less) than needed, or give too many (or too few) examples, etc. The PR should match the general flavor of the Reference here.

Is this well written?

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.

Resources

The Reference team has collected a set of resources about language specifications and technical writing.

• Language specs — It can be useful to learn how other languages are specified. This includes papers, standards, and commentary on how languages are specified.
• Style and writing guides — This contains a large list of different English and technical writing guides.