mirror of https://github.com/rust-lang/reference
Add a basic style guide.
This commit is contained in:
parent
8e7e6a03d8
commit
77a81ee3cb
|
@ -14,6 +14,11 @@ for the Reference. As such, we have the warning saying there's work that needs
|
|||
to be done. Eventually, we plan to make sure everything is well documented
|
||||
enough that we can remove the warning.
|
||||
|
||||
It is encouraged for you to read the [introduction] to familiarize yourself
|
||||
with the kind of content the reference is expected to contain and the
|
||||
conventions it uses. Also, the [style guide] provides more detailed guidelines
|
||||
for formatting and content.
|
||||
|
||||
## Critiquing the Reference
|
||||
|
||||
This is the easiest way to contribute. Basically, as you read the reference, if
|
||||
|
@ -63,7 +68,9 @@ This should include links to any relevant information, such as the
|
|||
stabilization PR, the RFC, the tracking issue, and anything else that would be
|
||||
helpful for writing the documentation.
|
||||
|
||||
[introduction]: src/introduction.md
|
||||
[issue tracker]: https://github.com/rust-lang/reference/issues
|
||||
[playpen]: https://play.rust-lang.org/
|
||||
[rust-lang/rust]: https://github.com/rust-lang/rust/
|
||||
[style guide]: STYLE.md
|
||||
[unstable]: https://doc.rust-lang.org/nightly/unstable-book/
|
||||
|
|
|
@ -0,0 +1,80 @@
|
|||
# Rust reference style guide
|
||||
|
||||
Some conventions and content guidelines are specified in the [introduction].
|
||||
This document serves as a guide for editors and reviewers.
|
||||
|
||||
## 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.
|
||||
|
||||
```
|
||||
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 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.
|
||||
|
||||
## 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
|
Loading…
Reference in New Issue