diff --git a/STYLE.md b/STYLE.md index f265aab3b..07621275c 100644 --- a/STYLE.md +++ b/STYLE.md @@ -3,18 +3,15 @@ Some conventions and content guidelines are specified in the [introduction]. This document serves as a guide for editors and reviewers. -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`. +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`. ## Markdown formatting * Use ATX-style heading with sentence case. -* Wrap long lines, preferably at 80-columns. -* Use reference links, with shortcuts if appropriate. 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. +* Use one line per sentence to make diffs nicer. + Do not wrap long lines. +* Use reference links, with shortcuts if appropriate. + 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. ``` Example of shortcut link: [enumerations] @@ -24,19 +21,17 @@ of these. To use it locally, run [enumerations]: types/enum.md ``` -* Links should be relative with the `.md` extension. 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. -* See the [Conventions] section for formatting callouts such as notes, edition - differences, and warnings. +* Links should be relative with the `.md` extension. + 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. +* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings. * Formatting to avoid: * Avoid trailing spaces. * Avoid double blank lines. ### Code examples -Code examples should use code blocks with triple backticks. The language -should always be specified (such as `rust`). +Code examples should use code blocks with triple backticks. +The language should always be specified (such as `rust`). ```rust println!("Hello!"); @@ -44,20 +39,16 @@ println!("Hello!"); See https://highlightjs.org/ for a list of supported languages. -Rust examples are tested via rustdoc, and should include the appropriate -annotations when tests are expected to fail: +Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail: * `edition2018` — If it is edition-specific. -* `no_run` — The example should compile successfully, but should not be - executed. +* `no_run` — The example should compile successfully, but should not be executed. * `should_panic` — The example should compile and run, but produce a panic. * `compile_fail` — The example is expected to fail to compile. -* `ignore` — The example shouldn't be built or tested. This should be avoided - if possible. 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 psuedo-code which is not valid Rust. An HTML comment such as - `` should be placed before the example - to explain why it is ignored. +* `ignore` — The example shouldn't be built or tested. + This should be avoided if possible. + 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. + An HTML comment such as `` should be placed before the example to explain why it is ignored. See the [rustdoc documentation] for more detail. @@ -66,18 +57,14 @@ See the [rustdoc documentation] for more detail. * Use American English spelling. * Use Oxford commas. * Idioms and styling to avoid: - * Avoid slashes for alternatives ("program/binary"), use conjunctions or - rewrite it ("program or binary"). - * Avoid qualifying something as "in Rust", the entire reference is about - Rust. + * Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary"). + * Avoid qualifying something as "in Rust", the entire reference is about Rust. ## Content -* Whenever there is a difference between editions, the differences should be - called out with an "Edition Differences" block. The main text should stick - to what is common between the editions. 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. +* Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block. + The main text should stick to what is common between the editions. + 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. [conventions]: src/introduction.md#conventions [introduction]: src/introduction.md