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

语言规则

参考手册中的条款被标记为命名的规则(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 而不是分别列出 i586i686x86_64。如果一条规则适用于所有 ELF 平台,应命名为 elf 而不是列出每个 ELF 操作系统)。
    • 如果语言没有提供名称,使用一个适当描述性但简短的名称。