|
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