Have you ever wondered how to create these feature annotations in your documentation?
This is done with the doc_cfg
feature. However, this is an unstable feature, and it cannot be used on stable Rust. This gist is a guide on how to work around that.
Add this to the top of your lib.rs:
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
The doc_auto_cfg
is yet another feature. What this does is automagically figuring out the necessary flags to place. If omitted you have to annotate these yourself.
You need cfg_attr
to control when these features are activated, so that your program will compile on stable Rust.
Add this to your cargo.toml to make docs.rs use it when you upload your crate.
[package.metadata.docs.rs]
# Enable all your features! Otherwise they will not show up in your documentation.
all-features = true
# Enable the unstable features
rustdoc-args = ["--cfg", "docsrs"]
To locally test, you have to set the cfg, and you have to use nightly rustdoc.
For example, on PowerShell, do...
$env:RUSTDOCFLAGS = "--cfg docsrs"
...and, after installing a nightly toolchain...
rustup install nightly
...render your documentation:
cargo +nightly doc --all-features --open
Flags are not correctly applied on re-exports from private modules: rust-lang/rust#83428
Duplicated functions are not deduplicated. If you write the following functions...
#[cfg(target_pointer_width = "32")]
fn foo(){
// 32 bit impl
}
#[cfg(target_pointer_width = "64")]
fn foo(){
// 64 bit impl
}
...this function will show up (if you're on a 64 bit system) as being only available on 64 bit.
To fix this, deduplicate the function and move the cfgs to its internals:
fn foo(){
#[cfg(target_pointer_width = "32")]
{
// 32 bit impl
}
#[cfg(target_pointer_width = "64")]
{
// 64 bit impl
}
}
The same applies for structs.
Also, this system is designed to work with features that are additive! If you have features that remove things (🙀), this will work much less well.