抓取的示例

Rustdoc 有一个不稳定的功能，它可以自动从 Cargo 工作区的 examples/ 目录中抓取正在文档化的条目的示例。这些示例将被包含在该条目的生成文档中。例如，如果您的库包含一个公共函数

// a_crate/src/lib.rs
pub fn a_func() {}

并且您有一个调用此函数的示例

// a_crate/examples/ex.rs
fn main() {
  a_crate::a_func();
}

那么这段代码片段将被包含在 a_func 的文档中。此文档由 Rustdoc 插入，crate 作者无法手动编辑。

如何使用此功能

此功能不稳定，因此您可以使用不稳定的 rustdoc-scrape-examples 标志调用 Rustdoc 来启用它

cargo doc -Zunstable-options -Zrustdoc-scrape-examples

要在 docs.rs 上启用此功能，请将此添加到您的 Cargo.toml 中

[package.metadata.docs.rs]
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]

它是如何工作的

当您运行 cargo doc 时，Rustdoc 将分析所有与 Cargo 的 --examples 过滤器匹配的 crate，以查找正在文档化的条目的实例。然后，Rustdoc 将在生成的文档中包含这些实例的源代码。

Rustdoc 有一些技术来确保这些示例不会让文档读者感到不知所措，并且不会撑爆页面大小

1. 对于给定的条目，页面中最多包含 5 个示例。其余示例只是指向源代码的链接。
2. 默认情况下仅显示一个示例，其余示例隐藏在切换按钮后面。
3. 对于包含示例的给定文件，只有包含示例的条目才会包含在生成的文档中。

对于给定的条目，Rustdoc 会根据示例的大小对其进行排序——较小的示例首先显示。

常见问题

我的示例没有在文档中显示

此功能使用 Cargo 的约定来查找示例。您应该确保 cargo check --examples 包含您的示例文件。