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
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
.
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:
Code examples should use code blocks with triple backticks.
The language should always be specified (such as 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.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。