rust-docs-guidelines

Rust 文档指南

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

指南

• 关键概念只应解释一次。其他所有文档都应使用文档内链接指向首次解释的位置。
• 提及 Rust 符号（类型、函数、常量等）时，始终使用文档内链接。
• 在 # Safety 部分中，将 valid 一词链接到 std 的指针有效性规则：写作 [valid]，并在文档块末尾添加此引用定义 —

  [valid]: https://doc.rust-lang.org/std/ptr/index.html#safety
  

  仅当它表示指针或内存有效性时才这样做 — valid UTF-8、有效的枚举变体、有效的 nul 终止符，以及字段必须相互一致的按值传递结构体，都应保留原样，因为 std 的定义并未涉及这些情况。 类似于 “must remain valid for the lifetime of the returned iterator” 的时长限定语确实表示这一含义，因此也要链接；它所增加的时长与有效性的含义无关。 回调参数则恰恰相反：std 的规则涵盖通过数据指针进行的访问，却不涵盖地址在给定 ABI 下是否可调用，因此应改为要求其签名为 [ABI-compatible]，并将其定义为 —

  [ABI-compatible]: https://doc.rust-lang.org/std/primitive.fn.html#abi-compatibility
  

  非文档注释 // SAFETY: 也保留原样：rustdoc 不会渲染它们，因此方括号会作为文本原样显示。
• 避免引用具体行号或行号范围，因为它们可能随时间变化。 如果文档需要附在函数或方法体内的特定代码段上，请使用行注释。
• 重点说明原因，而非做法。 尤其应避免在行注释中解释琐碎的实现细节。
• 使用文档内链接引用常量。不要在其他条目的文档中硬编码常量值。
• 与其重复说明，不如使用指向私有条目的文档内链接。在适用处添加 #[allow(rustdoc::private_intra_doc_links)]。