高级功能

此页面上列出的功能超出了其他主要类别的范围。

`#[cfg(doc)]`: 文档化平台特定或功能特定信息

对于条件编译，Rustdoc 以与编译器相同的方式处理您的板条箱。只有来自主机目标的内容可用（或者如果存在，则来自给定的 --target），其他所有内容都从板条箱中“过滤掉”。如果您的板条箱在不同的目标上提供不同的内容，并且您希望您的文档反映您提供的所有可用项目，这可能会导致问题。

如果您想确保 Rustdoc 无论目标平台是什么都能看到某个项目，您可以对其应用 #[cfg(doc)]。Rustdoc 在构建文档时会设置此标志，因此使用该标志的任何内容都将进入它生成的文档中。要将此应用于具有其他 #[cfg] 过滤器的项目，您可以编写类似 #[cfg(any(windows, doc))] 的内容。这将保留该项目，无论是在 Windows 上正常构建时，还是在任何地方进行文档化时。

请注意，此 cfg 不会传递给 doctests。

示例

#![allow(unused)]
fn main() {
/// Token struct that can only be used on Windows.
#[cfg(any(windows, doc))]
pub struct WindowsToken;
/// Token struct that can only be used on Unix.
#[cfg(any(unix, doc))]
pub struct UnixToken;
}

在这里，各个标记只能由依赖板条箱在其各自的平台上使用，但它们都将出现在文档中。

平台特定文档之间的交互

Rustdoc 没有一种神奇的方法来“好像”您为每个平台运行一次来编译文档（这种神奇的魔杖被称为 'rustdoc 的圣杯'）。相反，它一次看到您所有的代码，就像您向 Rust 编译器传递 --cfg doc 时一样。但是，Rustdoc 有一个诀窍，如果它确实收到平台特定代码，它可以处理平台特定代码。

要文档化您的板条箱，Rustdoc 只需要知道您函数的公共签名。特别是，它不需要知道任何函数是如何实现的，因此它会忽略所有类型错误和函数体中的名称解析错误。请注意，这不适用于函数体之外的任何内容：由于 Rustdoc 文档化您的类型，因此它必须知道这些类型是什么！例如，这段代码无论平台如何都能正常工作

pub fn f() {
    use std::os::windows::ffi::OsStrExt;
}

但这段代码不行，因为未知类型是函数签名的一部分

pub fn f() -> std::os::windows::ffi::EncodeWide<'static> {
    unimplemented!()
}

有关此允许的更现实的代码示例，请参阅 rustdoc 测试套件。

在文档搜索中添加项目的别名

此功能允许您在使用 rustdoc 搜索通过 doc(alias) 属性进行搜索时，为项目添加别名。示例

#![allow(unused)]
fn main() {
#[doc(alias = "x")]
#[doc(alias = "big")]
pub struct BigX;
}

然后，当您通过 rustdoc 搜索查找它时，如果您输入“x”或“big”，搜索将首先显示 BigX 结构体。

但是，文档别名名称有一些限制：您不能使用 " 或空格。

您可以通过使用列表同时添加多个别名

#![allow(unused)]
fn main() {
#[doc(alias("x", "big"))]
pub struct BigX;
}

自定义搜索引擎

如果您发现自己经常参考在线 Rust 文档，您可能会喜欢使用自定义搜索引擎。这使您可以直接使用导航栏搜索 rustdoc 网站。大多数浏览器都支持此功能，让您定义一个包含 %s 的 URL 模板，该模板将被替换为搜索词。例如，对于标准库，您可以使用此模板

https://doc.rust-lang.net.cn/stable/std/?search=%s

请注意，这将带您到一个列出所有匹配项的结果页面。如果您想立即导航到第一个结果（通常是最佳匹配），请改用以下方法

https://doc.rust-lang.net.cn/stable/std/?search=%s&go_to_first=true

此 URL 添加了 go_to_first=true 查询参数，可以附加到任何 rustdoc 搜索 URL 以自动转到第一个结果。

`#[repr(transparent)]`: 文档化透明表示

您可以在 Rust 参考和 Rustonomicon 中阅读有关 #[repr(transparent)] 本身的更多信息。

由于这种表示仅在具有非平凡大小或对齐的单个字段是公共的，并且文档没有另行说明的情况下才被视为公共 ABI 的一部分，因此 Rustdoc 有助于仅当非 1-ZST 字段是公共的或至少一个字段是公共的（如果所有字段都是 1-ZST 字段）时显示该属性。术语1-ZST 指的是对齐为 1 且大小为零的类型。

似乎可以使用 #[cfg_attr(not(doc), repr(transparent))] 手动隐藏该属性，如果您希望将表示声明为私有，即使非 1-ZST 字段是公共的也是如此。但是，由于当前的限制，这种方法并不总是保证有效。因此，如果您想这样做，无论您是否使用 cfg_attr，都应该始终用散文写下来。

Rustdoc 手册