You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: STYLE.md
+19-33
Original file line number
Diff line number
Diff line change
@@ -3,19 +3,15 @@
3
3
Some conventions and content guidelines are specified in the [introduction].
4
4
This document serves as a guide for editors and reviewers.
5
5
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`.
9
7
10
8
## Markdown formatting
11
9
12
10
* Use ATX-style heading with sentence case.
13
11
* Use one line per sentence to make diffs nicer.
14
12
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.
19
15
20
16
```
21
17
Example of shortcut link: [enumerations]
@@ -25,40 +21,34 @@ of these. To use it locally, run
25
21
[enumerations]: types/enum.md
26
22
```
27
23
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.
33
27
* Formatting to avoid:
34
28
* Avoid trailing spaces.
35
29
* Avoid double blank lines.
36
30
37
31
### Code examples
38
32
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`).
41
35
42
36
```rust
43
37
println!("Hello!");
44
38
```
45
39
46
40
See https://highlightjs.org/ for a list of supported languages.
47
41
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:
50
43
51
44
*`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.
54
46
*`should_panic` — The example should compile and run, but produce a panic.
55
47
*`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.
62
52
63
53
See the [rustdoc documentation] for more detail.
64
54
@@ -67,18 +57,14 @@ See the [rustdoc documentation] for more detail.
67
57
* Use American English spelling.
68
58
* Use Oxford commas.
69
59
* 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.
74
62
75
63
## Content
76
64
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.
0 commit comments