From 82b3f6d6ad339bf9ee16f8fce24daff3a7317658 Mon Sep 17 00:00:00 2001
From: Benjamin Herr <v@1d6.org>
Date: Thu, 11 Mar 2021 21:07:12 -0800
Subject: [PATCH 1/3] STYLE.md: Request one sentence per line.
---
STYLE.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/STYLE.md b/STYLE.md
index f265aab3b..983653bc2 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -10,7 +10,8 @@ of these. To use it locally, run
## Markdown formatting
* Use ATX-style heading with sentence case.
-* Wrap long lines, preferably at 80-columns.
+* 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
From 7bb13bfa8e8a267cf65bd91a1ce10707aea158ac Mon Sep 17 00:00:00 2001
From: Benjamin Herr <v@1d6.org>
Date: Thu, 11 Mar 2021 21:09:50 -0800
Subject: [PATCH 2/3] STYLE.md: Use one line per sentence.
---
STYLE.md | 52 +++++++++++++++++++---------------------------------
1 file changed, 19 insertions(+), 33 deletions(-)
diff --git a/STYLE.md b/STYLE.md
index 983653bc2..c5130c41e 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -3,19 +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.
* 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.
+* 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]
@@ -25,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!");
@@ -45,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
- `<!-- 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 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.
See the [rustdoc documentation] for more detail.
@@ -67,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
From a1100f175f27ba807f1c3de9ad2165e414728757 Mon Sep 17 00:00:00 2001
From: Benjamin Herr <v@1d6.org>
Date: Thu, 11 Mar 2021 21:11:13 -0800
Subject: [PATCH 3/3] STYLE.md: Fix typo.
---
STYLE.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/STYLE.md b/STYLE.md
index c5130c41e..07621275c 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -47,7 +47,7 @@ Rust examples are tested via rustdoc, and should include the appropriate annotat
* `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.
+ 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.