You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/authoring.md
-57Lines changed: 0 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,63 +12,6 @@ To verify that links are not broken, run `cargo xtask linkcheck`.
12
12
13
13
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.
14
14
15
-
## Special markdown constructs
16
-
17
-
The following are extensions provided by [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec).
18
-
19
-
### Rules
20
-
21
-
Most clauses should be preceded with a rule. Rules can be specified in the markdown source with the following on a line by itself:
22
-
23
-
```markdown
24
-
r[foo.bar]
25
-
```
26
-
27
-
The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`).
28
-
29
-
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.
30
-
31
-
In the HTML, the rules are clickable just like headers.
32
-
33
-
When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines:
34
-
35
-
1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to.
36
-
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.
37
-
* This content will be moved to `[!NOTE]` or more specific admonitions in the future.
38
-
3. Rust code examples and tests do not need their own rules.
39
-
4. Use the following guidelines for admonitions:
40
-
* Notes: Do not include a rule.
41
-
* 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.
42
-
* Target specific behavior: Always include the rule.
43
-
* Edition differences: Always include the rule.
44
-
5. The following keywords should be used to identify paragraphs when unambiguous:
45
-
*`intro`: The beginning paragraph of each section - should explain the construct being defined overall.
46
-
*`syntax`: Syntax definitions or explanations when BNF syntax definitions are not used.
47
-
*`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]`).
48
-
6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows:
49
-
* 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).
50
-
* Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule".
51
-
* Whenever possible, do not repeat previous components of the rule.
52
-
* 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/>.
53
-
* 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).
54
-
* Use an appropriately descriptive, but short, name if the language does not provide one.
55
-
56
-
#### Test rule annotations
57
-
58
-
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] which tracks how the rules are currently linked.
59
-
60
-
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.
61
-
62
-
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.
63
-
64
-
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).
65
-
66
-
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`.
67
-
68
-
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.
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).
4
+
5
+
## Rule labels
6
+
7
+
Most clauses should be preceded with a rule label. A rule label should be on a line by itself, and should look like this:
8
+
9
+
```markdown
10
+
r[foo.bar]
11
+
```
12
+
13
+
The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`).
14
+
15
+
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.
16
+
17
+
In the HTML, the rules are clickable just like headers.
18
+
19
+
## Rule guidelines
20
+
21
+
When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines:
22
+
23
+
1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to.
24
+
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.
25
+
- This content will be moved to `[!NOTE]` or more specific admonitions in the future.
26
+
3. Rust code examples and tests do not need their own rules.
27
+
4. Use the following guidelines for admonitions:
28
+
- Notes: Do not include a rule.
29
+
- 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.
30
+
- Target specific behavior: Always include the rule.
31
+
- Edition differences: Always include the rule.
32
+
5. The following keywords should be used to identify paragraphs when unambiguous:
33
+
-`intro`: The beginning paragraph of each section - should explain the construct being defined overall.
34
+
-`syntax`: Syntax definitions or explanations when BNF syntax definitions are not used.
35
+
-`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]`).
36
+
6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows:
37
+
- 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).
38
+
- Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule".
39
+
- Whenever possible, do not repeat previous components of the rule.
40
+
- 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/>.
41
+
- 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).
42
+
- Use an appropriately descriptive, but short, name if the language does not provide one.
43
+
44
+
[automatic link references]: ../links.md#rule-links
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] which tracks how the rules are currently linked.
4
+
5
+
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.
6
+
7
+
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.
8
+
9
+
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).
10
+
11
+
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`.
12
+
13
+
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.
0 commit comments