Skip to content

Commit 7bb13bf

Browse files
author
Benjamin Herr
committed
STYLE.md: Use one line per sentence.
1 parent 82b3f6d commit 7bb13bf

File tree

1 file changed

+19
-33
lines changed

1 file changed

+19
-33
lines changed

STYLE.md

+19-33
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,15 @@
33
Some conventions and content guidelines are specified in the [introduction].
44
This document serves as a guide for editors and reviewers.
55

6-
There is a [`style-check`](style-check/) tool which is run in CI to check some
7-
of these. To use it locally, run
8-
`cargo run --manifest-path=style-check/Cargo.toml src`.
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`.
97

108
## Markdown formatting
119

1210
* Use ATX-style heading with sentence case.
1311
* Use one line per sentence to make diffs nicer.
1412
Do not wrap long lines.
15-
* Use reference links, with shortcuts if appropriate. Place the sorted link
16-
reference definitions at the bottom of the file, or at the bottom of a
17-
section if there is an unusually large number of links that are specific to
18-
the section.
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.
1915

2016
```
2117
Example of shortcut link: [enumerations]
@@ -25,40 +21,34 @@ of these. To use it locally, run
2521
[enumerations]: types/enum.md
2622
```
2723
28-
* Links should be relative with the `.md` extension. Links to other rust-lang
29-
books that are published with the reference or the standard library API
30-
should also be relative so that the linkchecker can validate them.
31-
* See the [Conventions] section for formatting callouts such as notes, edition
32-
differences, and warnings.
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.
3327
* Formatting to avoid:
3428
* Avoid trailing spaces.
3529
* Avoid double blank lines.
3630
3731
### Code examples
3832
39-
Code examples should use code blocks with triple backticks. The language
40-
should always be specified (such as `rust`).
33+
Code examples should use code blocks with triple backticks.
34+
The language should always be specified (such as `rust`).
4135
4236
```rust
4337
println!("Hello!");
4438
```
4539

4640
See https://highlightjs.org/ for a list of supported languages.
4741

48-
Rust examples are tested via rustdoc, and should include the appropriate
49-
annotations when tests are expected to fail:
42+
Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail:
5043

5144
* `edition2018` — If it is edition-specific.
52-
* `no_run` — The example should compile successfully, but should not be
53-
executed.
45+
* `no_run` — The example should compile successfully, but should not be executed.
5446
* `should_panic` — The example should compile and run, but produce a panic.
5547
* `compile_fail` — The example is expected to fail to compile.
56-
* `ignore` — The example shouldn't be built or tested. This should be avoided
57-
if possible. Usually this is only necessary when the testing framework does
58-
not support it (such as external crates or modules, or a proc-macro), or it
59-
contains psuedo-code which is not valid Rust. An HTML comment such as
60-
`<!-- ignore: requires extern crate -->` should be placed before the example
61-
to explain why it is ignored.
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 psuedo-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.
6252

6353
See the [rustdoc documentation] for more detail.
6454

@@ -67,18 +57,14 @@ See the [rustdoc documentation] for more detail.
6757
* Use American English spelling.
6858
* Use Oxford commas.
6959
* Idioms and styling to avoid:
70-
* Avoid slashes for alternatives ("program/binary"), use conjunctions or
71-
rewrite it ("program or binary").
72-
* Avoid qualifying something as "in Rust", the entire reference is about
73-
Rust.
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.
7462

7563
## Content
7664

77-
* Whenever there is a difference between editions, the differences should be
78-
called out with an "Edition Differences" block. The main text should stick
79-
to what is common between the editions. However, for large differences (such
80-
as "async"), the main text may contain edition-specific content as long as
81-
it is made clear which editions it applies to.
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.
8268

8369
[conventions]: src/introduction.md#conventions
8470
[introduction]: src/introduction.md

0 commit comments

Comments
 (0)