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