包含什么（和排除什么）

很容易说一个项目中的所有内容都必须被记录下来，而且通常情况下这是正确的，但是我们如何才能做到这一点，以及是否存在不应该记录的内容？

在你的二进制项目的 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 将其包装在 main 函数中时，它将无法编译，因为未实现 ParseIntError trait。为了帮助你的受众和你的测试套件，此示例需要一些额外的代码

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

该示例在文档页面上相同，但是为任何尝试使用你的 crate 的人提供了额外的信息。有关测试的更多信息，请参见即将到来的文档测试章节。

要排除的内容

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

例如，一个使 crate 更容易实现的内部 macro! 在公共文档中出现时，可能会对用户造成潜在的危害。可能存在一个内部的 Error 类型，并且 impl 细节应该被隐藏，如 API 指南中所详述的那样。

自定义输出

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

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

在此博客中记录了使用此功能创建黑暗主题的一个好例子。请记住，通过单击右上角的齿轮图标，黑暗主题已经包含在 rustdoc 的输出中。向主题添加其他选项就像创建自定义主题 .css 文件并使用以下语法一样简单

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

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

rustdoc 文档

包含什么（和排除什么）

示例

要排除的内容

自定义输出