docs: enable feature(doc_cfg) when on nightly #440
Description
Feature Request
Crates
All
Motivation
Several tracing crates have a number of feature flags. Some of these feature flags control the presence of public API types, functions, etc. Currently, we attempt to list in the documentation what feature flag(s) are required to enable what APIs. However, it's easy to overlook this when reading the API docs, and it is relatively error-prone: it's possible to add a new feature-flagged API and forget to document the feature gates.
Proposal
The doc_cfg nightly feature allows RustDoc to be more aware of feature flags. When that feature is enabled, RustDoc will add a special banner indicating what feature flag(s) are required by an item with a conditional compilation attribute.
For example, the tracing-subscriber docs could look like this:
Since doc_cfg is an unstable feature, it requires the nightly toolchain. Therefore, we would need some way of enabling it only on nightly. A feature flag could be used, but this would have the disadvantage of breaking the build with --all-features on the stable toolchain, which is not ideal. As an alternative, other crates such as tonic use a RustDoc --cfg flag instead:
https://github.com/hyperium/tonic/blob/354d4fdc35dc51575f4c685fc04354f2058061ff/tonic/src/lib.rs#L77
https://github.com/hyperium/tonic/blob/354d4fdc35dc51575f4c685fc04354f2058061ff/tonic/src/lib.rs#L86
This --cfg flag can be added to the docs.rs metadata in the crate's Cargo.toml to cause docs.rs to enable the flag when building the docs:
https://github.com/hyperium/tonic/blob/354d4fdc35dc51575f4c685fc04354f2058061ff/tonic/Cargo.toml#L81-L83
We would probably want to also enable it on Netlify master/PR docs builds.
Alternatives
We could, alternatively, not do this, and continue with the current system of just explaining this in the feature flags in the RustDoc comments. However, I think this is much less clear to users reading the docs, and is probably slightly more work for contributors as well.
Another option is using a feature flag rather than a --cfg argument to enable the doc_cfg feature, but as I discussed, this would mean that building with --all-features would only work on nightly Rust. I don't think that is a good option.