如何在 `cargo doc` 生成的文档中获取功能需求标签？

Question

如果您查看 Tokio docs on docs.rs，有一个蓝色标签，表示必须激活某项功能才能访问此 API:

我也想为我的箱子启用它，如何实现？

Answer 1

坏消息是：目前它只是夜间功能。

好消息是：docs.rs 默认使用 nightly。

要使其正常工作，您只需启用 doc_cfg feature 并将 #doc(cfg) 应用于正在记录的项目

#![feature(doc_cfg)]

#[doc(cfg(feature = "macros"))]
pub fn test() {}

因为这是一个仅限夜间使用的功能，您可能不想一直启用它。 tokio 在其 Cargo.toml 中定义了以下内容以仅在 docs.rs 上启用此功能：

# docs.rs-specific configuration
[package.metadata.docs.rs]
# document all features
all-features = true
# defines the configuration attribute `docsrs`
rustdoc-args = ["--cfg", "docsrs"]

然后他们使用

// only enables the `doc_cfg` feature when
// the `docsrs` configuration attribute is defined
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
pub fn test() {}

Answer 2

在最近的 nightly 中（可能从 v1.57 开始），您可以使用功能 doc_auto_cfg（合并到 PR#90502）并且您不再需要手动标记 doc 的功能, 和之前一样写cfg:

#![feature(doc_auto_cfg)]

#[cfg(feature = "macros")]
pub fn test() {}

要在本地查看，运行 cargo +nightly doc --all-features.

如果您想继续对 cargo doc 以外的命令使用稳定版，您可以：

#![cfg_attr(doc, feature(doc_auto_cfg))] #[cfg(feature = "macros")] pub fn test() {}

UPDATE: 上述方法仍然需要doc-tests到运行每晚，还需要家属的doc命令到运行每晚。解决方法是我们只能在 nightly.

下启用 doc_auto_cfg 功能

在Cargo.toml中加入：

[build-dependencies]
rustc_version = "0.4.0"

创建一个包含以下内容的 build.rs 文件：

use rustc_version::{version_meta, Channel};

fn main() {
    // Set cfg flags depending on release channel
    let channel = match version_meta().unwrap().channel {
        Channel::Stable => "CHANNEL_STABLE",
        Channel::Beta => "CHANNEL_BETA",
        Channel::Nightly => "CHANNEL_NIGHTLY",
        Channel::Dev => "CHANNEL_DEV",
    };
    println!("cargo:rustc-cfg={}", channel)
}

然后我们可以这样启用功能doc_auto_cfg：

#![cfg_attr(all(doc, CHANNEL_NIGHTLY), feature(doc_auto_cfg))]

由于 docs.rs 默认使用 nightly，因此那里的文档将按您的预期显示。

如何在 `cargo doc` 生成的文档中获取功能需求标签？

How to get a feature requirement tag in the documentation generated by `cargo doc`?

rust

rustdoc