rust-docs-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Standards to follow when writing Rust documentation.

编写Rust文档时需遵循的标准。

Key concepts should be explained only once. All other documentation should use an intra-documentation link to the first explanation.
Always use an intra-documentation link when mentioning a Rust symbol (type, function, constant, etc.).
Avoid referring to specific lines or line ranges, as they may change over time. Use line comments if the documentation needs to be attached to a specific code section inside a function/method body.
Focus on why, not how. In particular, avoid explaining trivial implementation details in line comments.
Refer to constants using intra-documentation links. Don't hard-code their values in the documentation of other items.
Intra-documentation links to private items are preferable to duplication. Add
```
#[allow(rustdoc::private_intra_doc_links)]
```
where relevant.

核心概念仅需解释一次。其他所有文档应使用文档内链接指向首次解释的位置。
提及Rust符号（类型、函数、常量等）时，务必使用文档内链接。
避免引用特定行或行范围，因为这些内容可能会随时间变化。如果文档需要附加到函数/方法体内的特定代码段，请使用行注释。
重点说明“为什么”，而非“怎么做”。尤其要避免在行注释中解释无关紧要的实现细节。
使用文档内链接引用常量。不要在其他项的文档中硬编码常量的值。
对于私有项，使用文档内链接优于重复内容。在相关位置添加
```
#[allow(rustdoc::private_intra_doc_links)]
```
。