Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

译者序

本书是 《The Rust Reference Developer Guide》 的中文翻译，译者译作《Rust 参考手册开发者指南》。《The Rust Reference Developer Guide》是《The Rust Reference》的官方贡献指南，为编辑与审阅者提供了一套完整的协作规范。考虑到读者您未来若是愿意向上游仓库项目贡献代码，有一个中文翻译版本能够帮助您快速熟悉要求，故译者翻译了本书。

在翻译过程中，译者首先通过 DeepSeek 对全书进行初翻，随后人工通读全篇并对照上游代码的改动进行校对。翻译力求严谨、忠实原文，尽可能保持原文档的结构、语气与信息密度，不擅自增删文字细节，只在英文长句或被动语态影响中文阅读流畅性时，进行适度意译的调整，不改变原意。在专有名词、概念等术语上，译者社区中高质量的中文翻译内容，以期诸位读者在读到本书译文时，不会对某些概念或专有名词的翻译感到困惑。同时，代码与格式力求规范，每次提交均根据本书中的运行测试板块进行格式与链接检查，力争保证输出内容的质量。

本书的翻译通过同步上游仓库代码、翻译内容变化部分的方式保持所有翻译内容为最新。当前翻译的英文原文提交哈希为 5d5be50f，提交时间为 2026 年 5 月 21 日。

您可以通过以下方式阅读本书：

本书专业性强，译者能力有限，翻译难免会有疏漏和欠妥之处，恳请各位读者批评指正。如果您在阅读过程中发现任何问题，欢迎到项目仓库提交 Issues 或 Pull Requests 参与贡献翻译内容。

引言

感谢你对贡献 Rust 参考手册的关注。本文档概述了如何为参考手册做出贡献，并作为编辑者和评审者的指南。

为参考手册提供帮助有几种方式：评论参考手册、编辑参考手册、修正错误信息、添加示例和术语表条目，以及为 Rust 中新的或尚无文档的特性编写文档。

我们鼓励你阅读参考手册的引言，以熟悉参考手册预期包含的内容类型及其使用的约定。

评论参考手册

这是最简单的贡献方式。当你阅读参考手册时，如果发现令人困惑、错误或缺失的内容，可以针对参考手册提交 issue 来说明你的关切。

编辑参考手册

笔误和错误的链接时不时会出现。如果你发现了它们，欢迎提交 PR 来修复。

添加示例和术语表条目

示例非常棒。许多人只会阅读示例而忽略正文。理想情况下，每个特性的每个方面都应该有一个示例。

同样，参考手册有一个术语表。它不需要解释所有内容或包含所有可能的定义，但确实需要在现有基础上进行扩充。理想情况下，术语表中的条目应该链接到相关文档。

添加文档

有很多特性完全没有文档或文档质量很差。这是最困难但最有价值的任务。从 issue 跟踪器中选择一个未分配的 issue 并为其编写文档。

在编写过程中，你可能会发现打开一个 playground 来测试你所编写的内容会很方便。

你可以酌情从标准库和 Rustonomicon 中获取信息。

请注意，我们不为纯库特性（如线程和 I/O）编写文档，也不编写关于未来 Rust 的文档。文档的编写方式是将 Rust 的当前稳定版本视为最后一个版本。参考手册的 master 分支对应于 rust-lang/rust main 分支（“nightly”）上稳定的内容。如果你想编写关于未来 Rust 的内容，你需要 不稳定特性手册。

贡献流程

贡献前

对于非平凡的更改，我们鼓励人们在提交 PR 之前进行讨论。这使参考手册团队有机会更好地理解你的想法，并确保其符合参考手册的预期方向。通常，你应该在提交 pull request 之前提交 issue 或在 [Zulip]（Zulip）上发起讨论。

贡献流程概述

贡献的一般流程如下：

  1. 检出源代码。
  2. 安装 mdbook。
  3. 学习在本地构建本书。
  4. 对源文件进行更改。请务必遵循本书中关于风格、约定等的所有指南。
  5. 运行测试。
  6. 提交 pull request
  7. PR 将进入评审流程。
    • 关于可能经历的评审类型，请参见 评审策略。
    • 这可能需要一些时间，因为团队的时间有限。
  8. 一旦获得批准，团队成员将合并更改。
    • 团队可能会在合并前进行编辑性修改。
    • 更改可能需要几周时间才会出现在 nightly 网站上。更多细节请参见 发布。

办公时间

lang-docs 团队在周二 美国东部时间下午 3:30 举行办公时间。我们在 Jitsi Meet 上会面。请查看 [Zulip]（Zulip）频道以获取最新状态和可用性。

Zulip

Zulip 上有用于讨论参考手册的频道：

处理 issue

当 issue 被标记为 Help Wanted 时，团队正在寻求贡献来帮助解决它。

如果你想处理某个 issue，可以通过评论 @rustbot claim 来分配给自己。更多信息请参见 Issue 分配。

新特性

关于如何为新增特性编写文档，请参见 稳定化。

小改动

小改动 — 例如小的更正、措辞清理和格式修正 — 可以直接提交 PR 来完成。

大改动

大改动 — 例如大规模重写、重新组织和新增章节 — 应首先与参考手册团队讨论并获得批准。提交一个 issue（如果还没有的话）来讨论你感兴趣的更改类型。当参考手册团队能够提供帮助时，他们将与你合作来批准或对更改给出反馈。

提交 pull request

提交 pull request 时，请遵循以下指南：

  • 包含对更改内容及其原因的清晰描述。
  • 保持干净的 git 历史记录；每个提交都应解释更改的原因。
  • 在描述中使用 GitHub 关键词 来自动将 PR 链接到 issue。例如，写上 Closes #1234 会将 issue #1234 链接到该 PR。当 PR 被合并时，GitHub 将自动关闭该 issue。

当你的 PR 提交后，GitHub 会自动运行所有测试。GitHub 界面会显示绿色勾号（表示通过）或红色 X（表示失败）。PR 页面上有日志链接用于诊断任何问题。

PR 标签

PR 会用标签标记，例如 S-waiting-on-review 和 S-waiting-on-author，以指示其状态。任何人都可以使用 @rustbot 机器人来调整标签。如果 PR 被标记为 S-waiting-on-author，而你已经推送了希望被评审的新更改，你可以在 PR 上评论 @rustbot ready。机器人将切换 PR 上的标签。

有关这些命令的更多信息，请参见快捷方式文档。

稳定化流程

Rust 语言的新特性和更改通常需要更新参考手册以纳入变更。这可以在稳定化之前的任何时间完成，通常最好尽早准备 PR（前提是实现预计不会发生重大变化）。

此流程的一个例外是，当某个语言更改涉及语言中尚无文档的部分或参考手册中不完整的章节时。例如，类型推断目前没有文档记录，因此对类型推断细节的更改不需要更新参考手册。

然而，当某个新特性引入了一条可以独立于未文档化内容进行陈述的规则时，该规则仍应被记录。在这种情况下，将新规则添加到相关的占位章节中。当该章节最终被填充时，规则将被纳入完整文本。

Pull request

提交 PR 时，请包含尽可能多的信息链接，以便评审者能够更好地理解更改。这包括以下内容的链接（如果存在）：

  • 跟踪 issue。
  • rust-lang/rust 稳定化 pull request。
  • 稳定化报告。
  • 背景信息，如 RFC。
  • rustc 中实现该特性的文件（如果它被隔离到相对简洁的部分）。
  • rust-lang/rust 中的测试。

始终链接到跟踪 issue，以及（如果适用）稳定化 PR。除此之外，已经在跟踪 issue、稳定化报告或 PR 中出现的信息无需在 PR 描述中重复。

内联测试

如果 PR 记录了新稳定化的特性，其内联测试将在稳定化 PR 合并并且新的 nightly 编译器可用之前失败。我们计划在未来改进此流程（参见 #1864）。

发布流程

将参考手册内容纳入 Rust 发布并发布到网站的流程如下：

  1. 更改合入此仓库。
  2. Triagebot 将每两周自动将此仓库同步到 rust-lang/rust。参考手册在 rust-lang/rust 中作为子模块进行跟踪。
    • 这将在 rust-lang/rust 上打开一个需要合并的 PR，可能需要几天时间。
  3. 在 UTC 午夜，rust-lang/rust 默认分支上的内容将成为该 nightly 发布的一部分，并在几小时后发布到 https://doc.rust-lang.org/nightly/reference/。
  4. 按照 Rust 的发布流程，每 6 周，nightly 会提升为 beta（https://doc.rust-lang.org/beta/reference/），再过 6 周，它会被提升为稳定版（https://doc.rust-lang.org/stable/reference/）。

参考手册工具

参考手册使用 mdBook 将其源文件从 Markdown 转换为 HTML。更多信息请参见构建参考手册。mdbook-spec 扩展添加了参考手册使用的若干自定义功能。

关于测试，请参见运行测试。

构建参考手册

检出源代码

要构建参考手册，首先克隆项目：

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

安装 mdbook

参考手册使用 mdbook 构建。

首先，确保你安装了最新版本的 nightly Rust 编译器，因为运行测试需要它：

rustup toolchain install nightly

现在，确保你安装了 mdbook，因为构建参考手册需要它：

cargo install --locked mdbook

运行 mdbook

mdbook 提供了若干命令和选项来帮助你进行本书的工作：

  • mdbook build --open：构建本书并在 web 浏览器中打开。
  • mdbook serve --open：在 localhost 上启动一个 web 服务器。每当任何文件发生更改时，它会自动重新构建本书并刷新你的 web 浏览器。

本书内容由 SUMMARY.md 文件驱动，每个文件都必须在那里链接。更多信息请参见 https://rust-lang.github.io/mdBook/。

SPEC_RELATIVE

SPEC_RELATIVE=0 环境变量会使标准库的链接指向 https://doc.rust-lang.org/ 而不是相对路径。这在你本地浏览时很有用，因为通常你没有标准库的副本。

SPEC_RELATIVE=0 mdbook serve --open

发布的网站位于 https://doc.rust-lang.org/reference/（或使用 rustup doc 的本地文档）不设置此变量，这意味着它使用相对链接。这支持离线浏览，并链接到正确的版本（例如，https://doc.rust-lang.org/1.81.0/reference/ 中的链接将保持在 1.81.0 目录内）。

SPEC_DENY_WARNINGS

SPEC_DENY_WARNINGS=1 环境变量将 mdbook-spec 生成的所有警告变为错误。这在 CI 中使用，以确保本书内容没有任何问题。

SPEC_DENY_WARNINGS=1 mdbook serve --open

SPEC_RUST_ROOT

SPEC_RUST_ROOT 环境变量可用于指向 https://github.com/rust-lang/rust 检出的目录。测试链接功能使用它来查找链接到参考手册规则的测试。如果未设置此变量，测试将不会被链接。

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

mdbook-spec

mdbook-spec 是一个 mdBook 预处理器，为参考手册添加了若干功能。它提供：

环境变量

mdbook-spec 使用的一些环境变量在 构建参考手册 中有详细说明：

运行测试

你可以运行几类不同的测试（这些测试在 CI 中强制执行）：

所有测试

cargo xtask test-all

此命令运行下面列出的所有测试。

我们建议在提交 PR 之前最后一步运行此命令。它会运行 CI 通过所需的大部分测试。关于其具体功能，请参见 tools/xtask/src/main.rs。

内联测试

cargo xtask mdbook-test

此命令运行 Markdown 中内联的所有测试。内部使用 rustdoc 来运行测试，并支持所有相同的功能。任何带有 rust 语言的代码块都将被编译，除非被忽略。更多信息请参见示例。

此前的指南建议使用 mdbook test，但只有默认 toolchain 为 nightly 时才能可靠运行。

链接检查

cargo xtask linkcheck

此命令验证链接没有失效。它下载并使用托管在 rust-lang/rust 仓库中的 linkchecker 脚本。

这需要通过 rustup 安装的最新 nightly 以及 rust-docs 组件。

编译脚本后，它使用 mdbook 构建参考手册，然后扫描所有本地链接以验证它们是否有效，特别是跨不同书籍之间的链接。这不会检查任何网络链接。

风格检查

cargo xtask style-check

这使用 style-check 工具来强制执行各种格式化规则。

代码格式化

CI 使用 cargo fmt --check 来验证所有工具（如 mdbook-spec）的 Rust 源代码是否已正确格式化。所有代码必须使用 rustfmt 格式化。

mdbook-spec 测试

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

CI 对 mdbook-spec 运行 cargo test 来执行该工具本身的测试。

格式化

以下章节详细说明了参考手册源文件应如何格式化。

Markdown

其中一些规则有自动化检查。运行 cargo xtask style-check 可以在本地运行它们。

格式化风格

  • 使用 ATX 风格标题（不要用 Setext），并采用句首字母大写。
  • 不要使用 tab；只使用空格。
  • 文件必须以换行符结尾。
  • 行尾不能有空格。双空格有语义含义，但可能是不可见的。如果你需要硬换行，请使用尾部反斜杠。
  • 如果可能，避免连续的空行。
  • 不要对长行进行换行。这有助于评审源文件的差异。
  • 使用智能标点而不是 Unicode 字符。例如，使用 --- 表示 em dash 而不是 Unicode 字符。像 em dash 这样的字符在等宽编辑器中可能难以看到，而且某些编辑器可能没有方便的方法来输入这些字符。
  • 有关格式化注释、版本差异和警告等提示框的信息，请参见提示块。

代码块

  • 不要使用缩进的代码块；应使用带 3 个或更多反引号的围栏代码块。
  • 代码块应该有明确的语言标签。

链接

关于链接的更多信息，请参见链接。

  • 指向其他章节的链接应该是相对路径，并使用 .md 扩展名。

  • 指向与参考手册一起发布的其他 rust-lang 书籍的链接也应该是相对路径，这样链接检查器可以验证它们。请参见外部书籍链接。

  • 指向标准库的链接应使用 rustdoc 风格的链接，如标准库链接中所述。

  • 优先使用引用链接，在适当的地方使用快捷引用链接。将排序后的链接引用定义放在文件底部，或者如果某个小节有特别多的特定链接，就放在该小节的底部。

    Example of shortcut link: [enumerations]
Example of reference link with label: [block expression][block]

[block]: expressions/block-expr.md
[enumerations]: types/enum.md

提示块

mdbook-spec 提供了一些提示块，使用类似 GitHub 风格 Markdown 的样式。样式名称放置在引用块的开头，例如：

> [!WARNING]
> This is a warning.

> [!NOTE]
> This is a note.

> [!EDITION-2024]
> This is an edition-specific difference.

> [!EXAMPLE]
> This is an example.

颜色和样式定义在 theme/reference.css 中，转换和图标位于 tools/mdbook-spec/src/admonitions.rs 中。

关于如何使用这些提示块，请参见参考手册引言中的 约定。

语言规则

参考手册中的条款被标记为命名的规则（rule）。这提供了链接和引用单个条款的能力，以及链接到 rustc 测试套件的能力。

规则标签

大多数条款之前应该有一个规则标签。规则标签应该独占一行，看起来像这样：

r[foo.bar]

规则名称应该是小写的，用句点分隔各部分，从最通用到最具体（例如，r[array.repeat.zero]）。

可以使用 Markdown 通过其 ID 来链接规则，如 [foo.bar]。有自动链接引用使得任何规则都可以从书中的任何页面被引用。

在 HTML 中，这些规则是可点击的，就像标题一样。

规则指南

为新段落分配规则或修改规则名称时，请使用以下指南：

  1. 一个规则适用于一个核心思想，这在阅读其应用的段落时应能轻松确定。
  2. 除了“介绍“段落外，纯解释性、说明性或示例性内容不需要规则。如果说明性段落与前一段落没有直接关联，请使用硬换行（渲染换行）将其分开。
    • 这些内容将来会被移到 [!NOTE] 或更具体的提示块中。
  3. Rust 代码示例和测试不需要自己的规则。
  4. 对提示块使用以下指南：
    • 注释：不包含规则。
    • 警告：如果警告是从上一段得出的，或者警告是解释性的且不引入任何新规则，则省略规则。
    • 目标特定行为：始终包含规则。
    • 版本差异：始终包含规则。
  5. 在含义明确时，应使用以下关键词来标识段落：
    • intro：每个章节的开头段落。它应该从整体上解释正在定义的结构。
    • syntax：当不使用 BNF 语法定义时的语法定义或解释。
    • namespace：仅适用于程序项，指定该程序项在哪些命名空间中引入名称。也可以在其他地方定义命名空间时使用（例如，r[attribute.diagnostic.namespace]）。
  6. 当规则不属于上述关键词，或对于章节规则 ID 时，按如下方式命名子规则：
    • 如果规则命名了一个特定的 Rust 语言构造（例如，属性、标准库类型/函数或由关键字引入的概念），请使用该构造在语言中的名称，并适当调整大小写（但不要用 - 替换 _）。
    • 除了名称中有 _ 的 Rust 语言概念外，使用 - 字符来分隔“子规则“中的单词。
    • 尽可能不要重复规则的前几个部分。
    • 版本差异提示块通常应以行为发生改变的版本来命名。你应该能够将日期与 https://doc.rust-lang.org/edition-guide/ 中的章节对应起来。
    • 目标特定提示块通常应以它们适用的最不具体的目标属性来命名（例如，如果一条规则影响所有 x86 CPU，规则名称应包含 x86 而不是分别列出 i586、i686 和 x86_64。如果一条规则适用于所有 ELF 平台，应命名为 elf 而不是列出每个 ELF 操作系统）。
    • 如果语言没有提供名称，使用一个适当描述性但简短的名称。

rustc 测试注解

https://github.com/rust-lang/rust 中的测试可以链接到参考手册中的规则。规则将包含测试的链接，还有一个附录跟踪规则当前的链接状态。

tests 目录中的测试可以用 //@ reference: x.y.z 头部注解来链接到规则。如果一个文件覆盖多个规则，可以多次指定该头部。

编译器开发者不需要在测试中添加 reference 注解。但如果他们愿意提供帮助，他们的合作是受欢迎的。参考手册的作者和编辑负责确保每条规则都有相关的测试。

这些测试有助于评审者看到规则的行为。它们也对希望查看特定行为示例的读者有帮助。添加新规则时，你应该等到参考手册端被批准后才向 rust-lang/rust 提交 PR（以避免在我们决定使用不同名称时产生不必要的修改）。

始终使用可用的最具体的规则名称进行注解。例如，使用 asm.rules.reg-not-input 而不是更宽泛的 asm.rules。

完全覆盖是目标，但目前尚未达到预期。

示例

示例代码块

代码示例应使用带三个反引号的代码块。应始终指定语言（如 rust）。

#![allow(unused)]
fn main() {
println!("Hello!");
}

关于支持的语言列表，请参见 mdBook 支持的语言。

rustdoc 属性

Rust 示例通过 rustdoc 进行测试，应包含适当的注解：

  • edition2015、edition2018 等 — 如果示例是特定版本的（默认版本见 book.toml）。
  • no_run — 示例应该编译成功，但不应该执行。
  • should_panic — 示例应该编译并运行，但会产生 panic。
  • compile_fail — 示例预期编译失败。
  • ignore — 示例不应该被构建或测试。应尽可能避免。通常只有在测试框架不支持时（如外部 crate、模块或 proc-macro）或包含不是合法 Rust 的伪代码时才需要。应在示例前放置 HTML 注释，如 <!-- ignore: requires extern crate -->，来说明为什么被忽略。
  • Exxxx — 如果示例预期编译失败并带有特定的错误代码，请包含该代码，以便 rustdoc 检查是否使用了预期的错误代码。

更多细节请参见 rustdoc 文档。

合并示例

在演示成功情况时，可以在单个代码块中包含多个情况。但对于失败情况，每个示例必须出现在单独的代码块中，这样测试才能确保每种情况确实以适当的错误代码失败。

测试示例

Rust 代码块在 CI 中被测试。你可以通过运行 cargo xtask mdbook-test 来验证示例是否通过。

链接

本章说明参考手册中链接应如何处理。其中一些功能由 mdbook-spec 提供。

关于测试链接，也可参见链接检查器测试。

规则可以通过其 ID 使用 Markdown 进行链接，目标设置为规则 ID。自动链接引用使得任何规则都可以从书中的任何页面被引用。

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

你应该在不指定 URL 的情况下链接到标准库，方式类似于 rustdoc 文档内链接。一些示例：

我们可以链接到 Option 的页面：

[`std::option::Option`]

在这些链接中，泛型会被忽略，可以被包含：

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

如果我们不想在文本中显示完整路径，可以写成：

[`Option`](std::option::Option)

宏可以用 ! 结尾。这有助于消除歧义。例如，这指的是宏而不是模块：

[`alloc::vec!`]

也支持显式命名空间消歧义：

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

注意一些限制，例如：

遇到 rustdoc 限制时，可以考虑使用相对链接手动链接到正确的页面。例如，../std/arch/macro.is_x86_feature_detected.html。

在本地渲染参考手册时，默认使用相对链接以符合书籍的发布方式。这可能不是你想要的效果，所以你通常需要设置 SPEC_RELATIVE=0 环境变量，使链接指向在线站点。

所有语法产生式名称的链接定义都会自动生成。更多信息请参见语法自动链接。

This attribute uses the [MetaWord] syntax.

Explicit grammar links can have the `grammar-` prefix like [Type][grammar-Type].

Grammar links can also appear in link reference definitions, e.g. [type].

[type]: grammar-Type

指向与参考手册一起发布的其他书籍的链接应该是相对链接，指向对应的书籍。这使链接能够指向正确的版本，与离线文档一起工作，并被链接检查器检查。例如：

See [`-C panic`].

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

内部链接

在可能的情况下，内部链接应使用规则链接或语法链接。否则，链接应该是相对于文件路径的，并使用 .md 扩展名。

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

Rust 语法

参考手册的语法使用改良的类 BNF 语法（融合了正则表达式和其他任意元素）编写在 Markdown 代码块中。mdbook-spec 扩展解析这些规则并将其转换为可渲染的格式，包括铁路图。

代码块应该有一个语言字符串，包含单词 grammar、逗号和语法类别，像这样：

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

类别用于在附录的语法摘要页面上对类似产生式进行分组。

语法语法

语法本身的语法类似于 记法 中描述的那样，不过渲染上有一些差异。

用 @root 标记的“根“产生式是不会在任何其他产生式中使用的产生式。

语法记法的语法（用其自身的记法描述）如下：

Grammar -> Production+

BACKTICK -> U+0060

LF -> U+000A

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

Name -> <Alphanumeric or `_`>+

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

Sequence ->
        (` `* AdornedExpr)* ` `* Cut
      | (` `* AdornedExpr)+

AdornedExpr -> Prefix? Expr1 Quantifier? Suffix? Footnote?

Prefix -> NegativeLookahead

NegativeLookahead -> `!`

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

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

Quantifier ->
      Optional
    | Repeat
    | RepeatPlus
    | RepeatRange
    | RepeatRangeInclusive
    | RepeatRangeNamed

Optional -> `?`

Repeat -> `*`

RepeatPlus -> `+`

RepeatRange -> `{` ( Name `:` )? Range? `..` Range? `}`

RepeatRangeInclusive -> `{` ( Name `:` )? Range? `..=` Range `}`

RepeatRangeNamed -> `{` Name `}`

Range -> [0-9]+

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

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

NonTerminal -> Name

Break -> LF ` `+

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

Terminal -> BACKTICK ~[LF]+ BACKTICK

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

Characters ->
      CharacterRange
    | CharacterTerminal
    | CharacterName

CharacterRange -> Character `-` Character

Character ->
        BACKTICK <any char> BACKTICK
      | Unicode

CharacterTerminal -> Terminal

CharacterName -> Name

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

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

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

Cut -> `^` Sequence

通用格式是由空行分隔的一系列产生式。表达式如下：

表达式示例描述
UnicodeU+0060单个 Unicode 字符。
NonTerminalFunctionParameters按名称引用另一个产生式。
Break由渲染器内部使用，用于检测换行和缩进。
Comment// 单行注释。延伸到行尾的注释。
Terminal`example`用反引号包围的精确字符序列。
Charset[ `A`-`Z` `0`-`9` `_` ]从一组字符中选择，用空格分隔。有三种不同的形式。
CharacterRange[ `A`-`Z` ]一个字符范围。字符可以是 Unicode 表达式或用反引号包围的字面字符。
CharacterTerminal[ `x` ]单个字符，用反引号包围。
CharacterName[ LF ]一个非终结符，引用另一个产生式。
Prose<除 CR 外的任何 ASCII 字符>用尖括号包围的关于应匹配内容的英文描述。
Group(`,` Parameter)+将表达式分组以便确定优先级，例如将重复运算符应用于一系列其他表达式。
NegativeExpression~[` ` LF]匹配除给定 Charset、Terminal 或 Nonterminal 以外的任何内容。
CutExpr1 ^ Expr2 | Expr3硬剪切运算符。一旦序列中 ^ 之前的表达式匹配，序列的其余部分必须匹配，否则解析将无条件失败 — 任何封闭表达式都不能在剪切点之后回溯。
Sequence`fn` Name Parameters必须按顺序匹配的一系列表达式。
AlternationExpr1 | Expr2仅匹配给定表达式中的一个，用竖线字符分隔。
Suffix_except [LazyBooleanExpression]_为前一个表达式添加后缀，提供附加的英文描述，以脚标渲染。这里可以包含有限的 Markdown，但尽量避免使用除链接等基础内容以外的任何东西。
Footnote[^extern-safe]添加一个脚注，可以提供对用户可能有帮助的额外信息。脚注本身应在代码块外部定义，如普通 Markdown 脚注。
OptionalExpr?前面的表达式是可选的。
NegativeLookahead!Expr如果 Expr 不跟在后面且不消耗任何输入，则匹配。
RepeatExpr*前面的表达式重复 0 次或更多次。
RepeatPlusExpr+前面的表达式重复 1 次或更多次。
RepeatRangeExpr{2..4}前面的表达式在指定的次数范围内重复。任意边界都可以省略，就像 Rust 范围一样。
RepeatRangeInclusiveExpr{2..=4}前面的表达式在指定的闭区间次数范围内重复。下界可以省略。
RepeatRange (named)Expr{name:2..4}当名称在范围之前时，重复次数会绑定到该名称，以便后续的 RepeatRangeNamed 表达式可以引用它。同样适用于 RepeatRangeInclusive。
RepeatRangeNamedExpr{name}前面的表达式重复的次数由先前命名的 RepeatRange 或 RepeatRangeInclusive 确定。

自动链接

mdbook-spec 插件会自动在每一页上为所有产生式名称添加 Markdown 链接定义。要直接链接到一个产生式名称，只需将其用方括号包围，如 [ArrayExpression]。

在某些情况下，可能与规则名称的自动链接产生名称冲突。在这种情况下，可以使用 grammar- 前缀来消除歧义，如 [Type][grammar-Type]。当明确性有助于提高清晰度时，也可以使用该前缀。

产生式名称也可以在链接引用定义中使用，以提供自定义链接文本，可以带也可以不带 grammar- 前缀。

We accept any [type].

[type]: grammar-Type

We accept any [type].

[type]: Type

属性

属性应使用以下模板。示例给出了你应该使用的措辞，但如果属性不符合任何示例或者示例妨碍了清晰性，你可以偏离模板。

当添加一个属性（或语法中新的属性位置）时，请确保更新所有“在…上的属性“小节，这些小节列出了可以在各种位置上使用的属性。

r[PARENT.example]

example 属性

r[PARENT.example.intro] example [属性][attributes] …给出高层次的描述。

[!EXAMPLE]

#![allow(unused)]
fn main() {
// 这应该是一个非常基本的示例，展示该属性
// 以某种方式被使用。
#[example]
fn some_meaningful_name() {}
}

r[PARENT.example.syntax] 描述此属性接受的语法。你可以说明它使用某种预先存在的语法，如 MetaWord，或者定义一个显式的语法。如果有不同的形式，这里简要描述语法并链接到下面解释不同形式行为的相应规则。示例：

example 属性使用 [MetaWord] 语法。

example 属性使用 [MetaListPaths] 语法来指定一个…的列表。

example 属性使用 [MetaWord] 和 [MetaNameValueStr] 语法。

example 属性使用 [MetaWord]、[MetaListPaths] 和 [MetaNameValueStr] 语法。

example 属性使用 [MetaNameValueStr] 语法。接受的值是 "X" 和 "Y"。

example 属性使用 [MetaNameValueStr] 语法。字符串中的值必须是…

example 属性有以下形式：

  • [MetaWord]

    [!EXAMPLE]

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

  • [MetaNameValueStr] — 给定的字符串必须…

    [!EXAMPLE]

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

  • [MetaListNameValueStr] — 与 [MetaNameValueStr] 语法相同，给定的字符串必须…

    [!EXAMPLE]

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

example 属性的语法是：

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

r[PARENT.example.syntax.foo] example 属性的 [MetaNameValueStr] 形式提供了一种指定 foo 的方式。

[!EXAMPLE]

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

r[PARENT.example.allowed-positions] 解释可以使用此属性的有效位置。

请参阅编译器中的 check_attr 和 builtin_attrs.rs。别忘了某些属性只能作为内部属性或外部属性使用。示例：

example 属性只能应用于…

example 属性只能应用于 crate 根。

example 属性可以在允许使用属性的任何地方使用。

如果有未使用属性的警告，或者如果 rustc 错误地接受某些位置，请包含关于这些情况的说明。

Note

rustc 在其他位置使用时忽略但会发出 lint 警告。这在未来可能变为错误。

r[PARENT.example.duplicates] 解释当属性在同一个元素上多次使用时的行为。请参阅编译器中的 AttributeDuplicates。示例：

example 属性可以在一个形式上使用任意次数。

在一个形式上多次使用 example 与使用一次效果相同。

example 属性只能在…上使用一次。

只有首次在程序项上使用 example 才有效。

Note

rustc 对首次使用之后的任何使用都会发出 lint 警告。这在未来可能变为错误。

Note

rustc 对首次使用之后的任何使用都会发出向前兼容性 lint 警告。这在未来可能变为错误。

只有最后一次在程序项上使用 example 才有效。

Note

rustc 对最后一次使用之前的任何使用都会发出 lint 警告。这在未来可能变为错误。

只有最后一次在程序项上使用 example 才用于…

如果 example 属性在程序项上使用超过一次，则所有列出值的组合用于…解释它们如何合并。

r[PARENT.example.ATTR_NAME] 如果此属性不能与另一个属性一起使用，请指明每个冲突的属性。对两个属性都要这样做。示例：

example 属性不能与 [foo] 属性一起使用。

r[PARENT.example.unsafe] 如果这是一个 unsafe 属性，请解释其必须满足的安全条件。否则不要包含此小节。当添加新的 unsafe 属性时，请确保也更新 attributes.safety。示例：

example 属性必须标记为 [unsafe][attributes.safety]，因为…

r[PARENT.example.stdlib] 此规则说明该属性是否在标准库中导出。如果没有，请跳过此小节。示例：

example 属性在标准库 prelude 中导出为 [core::prelude::v1::example]。

r[PARENT.example.foo] 从这里开始，添加解释该属性所有行为的规则。如果属性非常简单，你可以只有一个名为 .behavior 的规则来解释其行为。更复杂的属性（如有多种输入类型或不同模式的属性）应将每一种作为一个单独的规则来描述。

风格指南

以下章节描述了参考手册中英文散文的首选风格。

措辞

使用美式英语拼写。

避免将某事物限定为“in Rust“；整个参考手册都是关于 Rust 的。

标点

使用牛津逗号。

避免使用斜杠表示替代（“program/binary”）；使用连词或重写短语（“程序或二进制文件”）。

评审策略

团队成员有权合并来自其他贡献者在 https://github.com/rust-lang/reference 仓库中的更改。根据所做更改的类型，有不同的评审指南：

评审原则

评审者和作者在评审过程中应关注以下若干关键原则：

  • 可理解性：参考手册中的散文应该能被项目的大多数成员理解。贡献应假定读者熟悉参考手册的其余内容，但在可能的情况下，各章节应通过链接到相关内容来促进这种理解。
  • 可辩护性：当 lang-docs 团队合并对参考手册的更改时，他们同意为此后的内容负责。团队成员需要对辩护和解释参考手册内容的正确性感到有信心。在可能的情况下，对参考手册的更改应通过简明的示例来支持任何主张以验证其正确性。
  • 风格：不期望作者在起草对参考手册的新贡献时具备规范编写者的能力。只要主张是可理解和可辩护的，PR 可以以随意基调或作者的个人风格而不是参考手册的风格来撰写。团队成员将在评审中带来编辑经验，并在必要时在合并前修改措辞、组织结构、风格等以符合参考手册。

策略更改

对团队运作方式的重大更改（如对本文档的更改）应得到团队的一致同意，不得有阻止性反对意见。

对诸如风格强制执行之类的小修改，可以由一位团队成员评审后完成，只要有很高的信心认为任何团队成员不太可能反对（例如，将已在实践中使用的指南正式化）且更改可以轻松回滚。

有意义的内容添加或更改

在添加或更改参考手册中的内容时，评审者应与适当的专家协商以验证更改。如果评审者对更改的正确性有高度信心、评审者对该主题非常熟悉或相关专家已经是 PR 的作者或积极参与了 PR，则可能不需要这样做。何时进行协商由评审者自行做出良好判断。

内容应始终遵循本贡献者指南中的指南。

小内容更改

对于小内容更改 — 如小的清理、措辞修正或格式更正 — 维护者可以直接将修正推送到 PR 分支并合并，无需咨询作者或其他评审者。

工具更改

工具的小更改可以在一个团队成员的评审下进行。这包括 bug 修复、不太可能有反对意见的小添加以及已经讨论过的添加。

重大更改，如内容编写方式的更改或工具工作方式的重大更改，应由团队批准，不得有阻止性反对意见。

评审流程流程图

在评审 pull request 时，问自己以下问题：

提出的更改是否正确？

如果我们不确定且无法自己轻松验证，我们会询问知道答案的人。

这是否对语言做出了新的保证？

如果这将对语言做出新的保证，这需要经过 lang 团队的接受（除非 lang 团队已经在其他地方明确接受了此保证）。如果对这些有任何不确定，请咨询 @traviscross。

我们会自己将此添加到参考手册吗？

有很多 PR 可能是正确的，但当我们看到它们时，我们内心深处觉得这实在不是我们会费心自己去写的内容。我们不想仅仅因为一个 PR 摆在我们面前且不是明显错误就接受它。它应该明显增加价值。

这在编辑上是否合理？

有些 PR 试图过度“推销“语言，或试图解释得比需要的更多（或更少），或给出过多（或过少）的示例等。PR 应该与参考手册的整体风格相匹配。

这写得好吗？

有些 PR 是正确的但措辞生硬或有排版问题。如果更改很小，我们会直接在分支上添加提交来清理然后合并。

本策略尚未涵盖从相关团队获得最终批准的流程。

资源

参考手册团队收集了一组关于语言规范和写作的资源。

  • 语言规范 — 了解其他语言是如何规范的会很有用。这包括论文、标准，以及关于如何规范语言的评论。
  • 风格和写作指南 — 这包含了一个包含各种英文和技术写作指南的大列表。