|
1 | 1 | # Rust reference style guide |
2 | 2 |
|
3 | | -Some conventions and content guidelines are specified in the [introduction]. |
4 | | -This document serves as a guide for editors and reviewers. |
| 3 | +See the [Authoring Guide] for details on the style used in the reference. |
5 | 4 |
|
6 | | -There is a [`style-check`](style-check/) tool which is run in CI to check some of these. To use it locally, run `cargo run --manifest-path=style-check/Cargo.toml src`. |
7 | | - |
8 | | -## Markdown formatting |
9 | | - |
10 | | -* Use ATX-style heading with sentence case. |
11 | | -* Use one line per sentence to make diffs nicer. |
12 | | - Do not wrap long lines. |
13 | | -* Use reference links, with shortcuts if appropriate. |
14 | | - Place the 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 that are specific to the section. |
15 | | - |
16 | | - ``` |
17 | | - Example of shortcut link: [enumerations] |
18 | | - Example of reference link with label: [block expression][block] |
19 | | -
|
20 | | - [block]: expressions/block-expr.md |
21 | | - [enumerations]: types/enum.md |
22 | | - ``` |
23 | | -
|
24 | | -* Links should be relative with the `.md` extension. |
25 | | - Links to other rust-lang books that are published with the reference or the standard library API should also be relative so that the linkchecker can validate them. |
26 | | -* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings. |
27 | | -* Formatting to avoid: |
28 | | - * Avoid trailing spaces. |
29 | | - * Avoid double blank lines. |
30 | | -
|
31 | | -### Code examples |
32 | | -
|
33 | | -Code examples should use code blocks with triple backticks. |
34 | | -The language should always be specified (such as `rust`). |
35 | | -
|
36 | | -```rust |
37 | | -println!("Hello!"); |
38 | | -``` |
39 | | - |
40 | | -See https://highlightjs.org/ for a list of supported languages. |
41 | | - |
42 | | -Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail: |
43 | | - |
44 | | -* `edition2015` or `edition2018` --- If it is edition-specific (see `book.toml` for the default). |
45 | | -* `no_run` --- The example should compile successfully, but should not be executed. |
46 | | -* `should_panic` --- The example should compile and run, but produce a panic. |
47 | | -* `compile_fail` --- The example is expected to fail to compile. |
48 | | -* `ignore` --- The example shouldn't be built or tested. |
49 | | - This should be avoided if possible. |
50 | | - Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. |
51 | | - An HTML comment such as `<!-- ignore: requires extern crate -->` should be placed before the example to explain why it is ignored. |
52 | | - |
53 | | -See the [rustdoc documentation] for more detail. |
54 | | - |
55 | | -## Language and grammar |
56 | | - |
57 | | -* Use American English spelling. |
58 | | -* Use Oxford commas. |
59 | | -* Idioms and styling to avoid: |
60 | | - * Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary"). |
61 | | - * Avoid qualifying something as "in Rust", the entire reference is about Rust. |
62 | | - |
63 | | -## Content |
64 | | - |
65 | | -* Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block. |
66 | | - The main text should stick to what is common between the editions. |
67 | | - However, for large differences (such as "async"), the main text may contain edition-specific content as long as it is made clear which editions it applies to. |
68 | | - |
69 | | -[conventions]: src/introduction.md#conventions |
70 | | -[introduction]: src/introduction.md |
71 | | -[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html |
| 5 | +[Authoring Guide]: docs/authoring.md |
0 commit comments