如何阅读 rustdoc 输出

Rustdoc 的 HTML 输出包含一个友好且有用的导航界面，使用户更容易浏览和理解您的代码。本章涵盖了该界面的主要功能，对于文档作者和用户来说都是一个很好的起点。

结构

rustdoc 的输出分为三个部分。每个页面的左侧是一个快速导航栏，显示有关当前条目的上下文信息。页面的其余部分由顶部的搜索界面和下面的当前项目文档组成。

项目文档

屏幕的大部分空间被当前正在查看的项目的文档文本占据。顶部是一些一目了然的信息和控件：

  • 项目的类型和名称，例如“结构体 std::time::Duration”，
  • 一个将项目路径复制到剪贴板的按钮，这是一个剪贴板项
  • 一个用于折叠或展开该项目的顶层文档的按钮（[+] 或 [-]），
  • 如果配置并且存在，则链接到源代码 ([src])（如果文档是用 cargo doc --no-deps 创建的，则源代码可能不可用），
  • 以及该项目在标准库中变为稳定的版本（如果它是一个标准库中的稳定项目）。

下方是该项目的主要文档，包括定义或函数签名（如果适用），然后是 Rust 类型的字段或变体列表。最后，该页面列出了关联的函数和 trait 实现，包括 rustdoc 知道的自动和 blanket 实现。

部分

别名类型

类型别名在编译时扩展为其别名类型。这可能涉及用类型别名定义提供的类型替换目标类型中的部分或全部类型参数。“别名类型”部分显示此扩展的结果，包括公共字段或变体的类型，这些类型可能取决于这些替换。

此文档中的子标题、变体、字段和许多其他内容都是锚点，可以单击并深度链接到，这是一种很好的方式来精确传达您所说的内容。当鼠标悬停或获得键盘焦点时，带有锚点的行旁边会出现排版字符“§”。

导航栏

例如，在查看 crate 根目录的文档时，它会显示文档包中记录的所有 crate，以及指向当前 crate 中可用的模块、结构体、trait、函数和宏的快速链接。在顶部，它会显示一个可配置的徽标以及当前 crate 的名称和版本，或正在显示其文档的当前项目。

主题选择器和搜索界面

当在启用了 JavaScript 的浏览器中查看 rustdoc 的输出时，页面顶部会出现一个动态界面，该界面由搜索界面、帮助屏幕和选项组成。

也支持路径，您可以查找 Vec::new 或 Option::Some 甚至 module::module_child::another_child::struct::field。空格字符被视为与 :: 相同，因此如果您输入 Vec new，它将被视为与 Vec::new 相同。

快捷键

在页面的其他位置聚焦时按 S 会将焦点移动到搜索栏，按 ? 会显示帮助屏幕，其中包含所有这些快捷键以及更多内容。

当搜索结果被聚焦时，左右箭头在选项卡之间移动，上下箭头在结果之间移动。按回车键或返回键会打开突出显示的结果。

当查看项目的文档时，加号和减号键会展开和折叠文档中的所有部分。