Use `docsrs` attribute to indicate feature-gated items in documentation

[newpavlov]

In code it looks like this:

#[cfg(feature = "my_feature")]
#[cfg_attr(docsrs, doc(cfg(feature = "my_feature")))]
struct Foo;

And in Cargo.toml:

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

Rendered result can be seen for example in the digest docs.

Also I think it will be nice to document crate features and indicate those enabled by default in the lib.rs docs.

[dhardy]

Aha, you're referring to this addition. It's still unstable and there are some grievances with the current presentation, but probably this would be okay for Rand.

Is there any reason not to just use #[cfg_attr(nightly, ...)] ?

[newpavlov]

Well, either way it will be better than the current situation, when users could be easily confused with feature settings.

Is there any reason not to just use #[cfg_attr(nightly, ...)] ?

I am not sure, I've just proposed to use an approach which we use in RustCrypto right now. :)

The following code:

#[cfg_attr(nightly, doc(cfg(feature = "my_feature")))]
pub fn foo() {
    println!("Hello, world!");
}

and cargo +nightly doc didn't produce the desired result. But maybe I am doing something wrong.

[dhardy]

nightly is still a feature flag (in rand's Cargo.toml). Cfg items are usually specified in build.rs scripts IME. Unimportant.

Yes, it does look like an improvement overall. I believe docs.rs uses nightly Rust for docs (as does our github.io generator), so it should be fine.