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