包含（和排除）的内容

很容易说项目中的所有内容都必须有文档，而且很多时候这是正确的，但我们如何才能做到这一点，以及有哪些东西不属于文档？

在二进制项目中的 src/lib.rs 或 main.rs 文件顶部，包含以下属性

#![allow(unused)]
#![warn(missing_docs)]
fn main() {
}

现在运行 cargo doc 并检查输出。以下是一个示例

 Documenting docdemo v0.1.0 (/Users/username/docdemo)
warning: missing documentation for the crate
 --> src/main.rs:1:1
  |
1 | / #![warn(missing_docs)]
2 | |
3 | | fn main() {
4 | |     println!("Hello, world!");
5 | | }
  | |_^
  |
note: the lint level is defined here
 --> src/main.rs:1:9
  |
1 | #![warn(missing_docs)]
  |         ^^^^^^^^^^^^

warning: 1 warning emitted

    Finished dev [unoptimized + debuginfo] target(s) in 2.96s

作为库作者，添加 lint #![deny(missing_docs)] 是一个很好的方法，可以确保项目不会偏离良好文档化的方向，而 #![warn(missing_docs)] 则是朝着全面文档化迈进的好方法。

在即将到来的章节 Lints 中有更多 lint。

示例

当然，这被设计得很简单，但文档的力量的一部分在于展示易于理解的代码，而不是现实的代码。文档通常会对错误处理采取捷径，因为示例可能会变得很复杂，因为需要为一个简单的示例设置所有必要的条件。

Async 就是一个很好的例子。为了执行 async 示例，需要一个执行器。示例通常会对此采取捷径，并让用户弄清楚如何将 async 代码放入自己的运行时中。

最好不要在示例中使用 unwrap()，如果错误处理组件使示例难以理解，则可以隐藏其中一些组件。

/// Example
/// ```rust
/// let fourtytwo = "42".parse::<u32>()?;
/// println!("{} + 10 = {}", fourtytwo, fourtytwo+10);
/// ```

当 rustdoc 将其包装在主函数中时，它将无法编译，因为 ParseIntError 特性未实现。为了帮助您的受众和测试套件，此示例需要一些额外的代码

/// Example
/// ```rust
/// # fn main() -> Result<(), std::num::ParseIntError> {
/// let fortytwo = "42".parse::<u32>()?;
/// println!("{} + 10 = {}", fortytwo, fortytwo+10);
/// #     Ok(())
/// # }
/// ```

该示例在文档页面上是相同的，但它具有额外的信息，可供任何尝试使用您的板条箱的人使用。有关测试的更多信息，请参阅即将到来的 文档测试 章节。

排除的内容

您的公共接口的某些部分可能会默认包含在 rustdoc 的输出中。#[doc(hidden)] 属性可以隐藏实现细节，以鼓励使用板条箱的惯用方式。

例如，一个内部 macro! 使板条箱更容易实现，但当它出现在公共文档中时，它可能会成为用户的绊脚石。可能存在一个内部 Error 类型，并且应该隐藏 impl 细节，如 API 指南 中所述。

自定义输出

可以将自定义 css 文件传递给 rustdoc 并设置文档的样式。

rustdoc --extend-css custom.css src/lib.rs

使用此功能创建深色主题的一个很好的例子在 此博客 中有记录。请记住，深色主题已包含在 rustdoc 输出中，只需单击右上角的齿轮图标即可。向主题添加更多选项就像创建自定义主题 .css 文件并使用以下语法一样简单

rustdoc --theme awesome.css src/lib.rs

以下是一个新主题的示例，Ayu。