高级特性

本页列出的特性不属于其他主要类别。

`#[cfg(doc)]`：记录特定平台或特定功能的信息

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

如果你想确保 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;
}

在这里，各个 token 只能由它们各自平台上的依赖 crate 使用，但它们都会出现在文档中。

特定于平台的文档之间的交互

Rustdoc 没有一种神奇的方法可以“像”你为每个平台运行一次那样编译文档（这种魔杖被称为 “rustdoc 的圣杯”）。相反，它会一次性看到你的所有代码，就像你传递给它 --cfg doc 时 Rust 编译器会做的那样。主要区别在于 rustdoc 不会运行所有的编译器 pass，这意味着一些无效的代码不会发出错误。

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

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

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

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

但是，文档别名名称有一些限制：它们不能包含引号（'、"）或大多数空格。如果别名不是以 ASCII 空格开头或结尾，则允许使用 ASCII 空格。

你可以通过使用列表一次添加多个别名

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

自定义搜索引擎

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

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

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

http://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 的一部分，因此，如果且仅当非 1-ZST 字段是公共的，或者如果所有字段都是 1-ZST 字段时至少有一个字段是公共的，Rustdoc 才会显示该属性。术语 *1-ZST* 是指一字节对齐和零大小的类型。

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

rustdoc book