[rustc.git] / src / doc / reference / STYLE.md

# Rust reference style guide

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`.

## 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.

    ```
    Example of shortcut link: [enumerations]
    Example of reference link with label: [block expression][block]

    [block]: expressions/block-expr.md
    [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.
* 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`).

```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:

* `edition2018` — If it is edition-specific.
* `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 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.

## Language and grammar

* 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.

## 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.

[conventions]: src/introduction.md#conventions
[introduction]: src/introduction.md
[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html
Commit	Line	Data
ba9703b0 XL	1	# Rust reference style guide
	2
	3	Some conventions and content guidelines are specified in the [introduction].
	4	This document serves as a guide for editors and reviewers.
	5
cdc7bbd5	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`.
29967ef6	7
ba9703b0 XL	8	## Markdown formatting
	9
	10	* Use ATX-style heading with sentence case.
cdc7bbd5 XL	11	* Use one line per sentence to make diffs nicer.
	12	Do not wrap long lines.
	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.
ba9703b0 XL	15
	16	```
	17	Example of shortcut link: [enumerations]
	18	Example of reference link with label: [block expression][block]
	19
	20	[block]: expressions/block-expr.md
	21	[enumerations]: types/enum.md
	22	```
	23
cdc7bbd5 XL	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.
ba9703b0 XL	27	* Formatting to avoid:
	28	* Avoid trailing spaces.
	29	* Avoid double blank lines.
	30
	31	### Code examples
	32
cdc7bbd5 XL	33	Code examples should use code blocks with triple backticks.
cdc7bbd5 XL	34	The language should always be specified (such as `rust`).
ba9703b0 XL	35
	36	```rust
	37	println!("Hello!");
	38	```
	39
	40	See https://highlightjs.org/ for a list of supported languages.
	41
cdc7bbd5	42	Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail:
ba9703b0 XL	43
ba9703b0 XL	44	* `edition2018` — If it is edition-specific.
cdc7bbd5	45	* `no_run` — The example should compile successfully, but should not be executed.
ba9703b0 XL	46	* `should_panic` — The example should compile and run, but produce a panic.
ba9703b0 XL	47	* `compile_fail` — The example is expected to fail to compile.
cdc7bbd5 XL	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 pseudo-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.
ba9703b0 XL	52
	53	See the [rustdoc documentation] for more detail.
	54
	55	## Language and grammar
	56
	57	* Use American English spelling.
	58	* Use Oxford commas.
	59	* Idioms and styling to avoid:
cdc7bbd5 XL	60	* Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary").
cdc7bbd5 XL	61	* Avoid qualifying something as "in Rust", the entire reference is about Rust.
ba9703b0 XL	62
	63	## Content
	64
cdc7bbd5 XL	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.
ba9703b0 XL	68
	69	[conventions]: src/introduction.md#conventions
	70	[introduction]: src/introduction.md
	71	[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html