rustdoc で各アイテムに必要なフィーチャーを表示する方法について。
Docs.rs との連携用の構成値 docsrs を、不安定な機能を有効化するためのフラグとして利用する。なお、docsrs の導入方法は、Docs.rs とローカル環境で少し異なる。そのため、それぞれ個別に指定しなければならない。
以下では、フィーチャー my_feature の有効時のみ、関数 my_func が利用可能になる。
そして、その事について API ドキュメントに掲載するようにしている。
config.toml ファイルの編集rustdoc コマンドの引数を指定。
my_feature を導入 (デフォルトでの使用有無も指定)。
# ...
[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "docsrs"]
[features]
default = ["my_feature"]
my_feature = []
# ...
フィーチャーを表示する方法は二通りある。
ただ、普段使いには一括指定の方法のみで十分だろう。
不安定な機能 doc_auto_cfg を使用する。
この場合、main.rs や lib.rs で全体設定を行うだけでよい。
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#[cfg(feature = "my_feature")]
pub fn my_func() {}
不安定な機能 doc_cfg を使用する。
この場合、関数などの各アイテムごとに設定が必要になる。
#![cfg_attr(docsrs, feature(doc_cfg))]
#[cfg(feature = "my_feature")]
#[cfg_attr(docsrs, doc(cfg(feature = "my_feature")))]
pub fn my_func() {}
ローカルのドキュメント生成コマンドで docsrs を有効化する方法は二通りある。
どちらが良いかは、そのプロジェクトにおける config.toml ファイルの取扱による。もし、それが個人用の設定ファイル扱いで、Git などのバージョン管理システムの対象外なら、気軽に編集できるので、設定ファイルから有効化するほうが楽になる。
docsrs をコマンド引数から有効化
以下では、docsrs をコマンド引数から有効化している。
> cargo +nightly --config 'build.rustdocflags = [\"--cfg\", \"docsrs\"]' doc
docsrs を設定ファイルから有効化
以下では、docsrs を設定ファイルから有効化している。
[build]
rustdocflags = ["--cfg", "docsrs"]
この場合、コマンドは単純になる。
> cargo +nightly doc