How to document optional features in API docs

For example, in this tokio-rs doc, there is the

This is supported on crate feature rt only.

How do we add that do the docs? I can't find it anywhere; tokio's source code does not seem to have that explicitly.

1 Like

It's an unstable attribute. Tracking issue. In the future it's hoped that the docs will get it right automatically, with the attribute only existing for a manual override.

1 Like

I'm a Tokio maintainer. Here are the steps to do this:

First you add this to your Cargo.toml:

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

This will make docs.rs compile your documentation with RUSTFLAGS="--cfg docsrs" set. We can use this to conditionally enable nightly features when building documentation, but not when building it normally.

Now you add this to your lib.rs file:

#![cfg_attr(docsrs, feature(doc_cfg))]

Then, on anything that needs such an annotation, you add the following

#[cfg_attr(docsrs, doc(cfg(feature = "rt")))]

This supports all of the syntax that #[cfg(...)] does, including stuff like platform-specifiers and any/all. Tokio often sets this annotation using the macros in src/macros/cfg.rs. Note that the annotation works recursively, so putting it on a module also affects the stuff inside (sometimes, it's a bit flaky).

Finally, when building the documentation locally, you run the following command:

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

Awesome, thanks a lot. I had to change it to RUSTDOCFLAGS="--cfg docsrs" to the local run. Tokio is using the same on the CI. So,

RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features full

seems sufficient here (RUSTFLAGS is not needed apparently).

1 Like

Ah I mixed them up, yes. The RUSTFLAGS variable is for setting stuff in dependencies of the crate being documented. I edited the previous post.

1 Like

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.