🦀

ライブラリクレートでは`doc_cfg`や`doc_auto_cfg`を有効にするのがおすすめ

2025/03/11に公開

rustdocでdoc_cfg機能やdoc_auto_cfg機能を有効にすると、条件付きコンパイルに関する情報をrustdocに伝えることができます。
これらの機能を有効にすると、以下のようにそのアイテムが特定のfeatureフラグが有効な場合や特定のプラットフォームでのみ利用可能なことを説明するバナーを表示できます。

表示結果
unixモジュールはUnix環境でのみ利用可能

表示結果
nowメソッドはstdフラグが有効な場合のみ利用可能

設定方法

これらの機能はまだ不安定なのでcfg_attrを使ってdocsrsが定義されている場合にのみ機能を有効にします。

src/lib.rs

#![cfg_attr(docsrs, feature(doc_cfg))]
// または
#![cfg_attr(docsrs, feature(doc_auto_cfg))]

doc_cfg機能が有効な場合にunixモジュールにバナーを表示するには以下のようにします。

src/lib.rs

#[cfg(unix)]
#[cfg_attr(docsrs, doc(cfg(unix)))]
pub use crate::platform::unix;

doc_auto_cfg機能が有効な場合にnowメソッドにバナーを表示するには以下のようにします。

src/lib.rs

#[cfg(feature = "std")]
pub fn now() -> Self {
    ...
}

doc_auto_cfg機能はdoc_cfg機能を拡張した機能で、doc(cfg(...))を追加しなくても自動的にバナーを表示できます。

多くの場合はこれらの機能は機能しますが、以下のようにcfg_attrを使用して特定のfeatureフラグが有効な場合にのみトレイトを導出する場合は現時点ではバナーは表示されません。

src/lib.rs

#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Params {
    ...
}

docs.rsでバナーを表示する

docs.rsでバナーを表示するには以下のようにします。

Cargo.toml

[package.metadata.docs.rs]
# 全てのfeatureフラグを有効にできない場合は適宜変更する
all-features = true
# `cfg`が`docsrs`の場合は不要
rustdoc-args = ["--cfg", "docsrs"]

docs.rsでは既定のcfgとしてdocsrsが定義されるので、cfgがdocsrsの場合はrustdoc-argsは不要です。

ローカル環境でバナーを表示する

ローカル環境でバナーを表示するには以下のようにRUSTDOCFLAGS環境変数に--cfg cfgを設定してcargo docを実行します。

env RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features

GitHubで編集を提案

設定方法

docs.rsでバナーを表示する

ローカル環境でバナーを表示する

Discussion