Merge pull request #980 from ben0x539/style

apply #950 to STYLE.md

Author: ehuss

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,40 +21,34 @@ 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!");
 ```
 
 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
-  `<!-- ignore: requires extern crate -->` 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 `<!-- ignore: requires extern crate -->` 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