cargo doc: include all available features in generated docs.

[nathan-at-least]

Describe the problem you are trying to solve

Problem: I can't find the feature-gated API's I need from dependencies by viewing the local cargo doc docs. Instead I have to either do online searches or go view ~/.cargo/registry/src/…/<CRATE>-<VERSION>/Cargo.toml and even then sometimes guess which features are relevant.

Describe the solution you'd like

Minimum Viable Solution:

When I open the crate-level docs using cargo doc --open, I would like it to have a section called "Features" on the top-level page, or linked from the side-bar to the left. That section lists the features that are currently enabled and all of the available disabled features, with clear markings for which state each feature is in: enabled or disabled.

Ideal Solution:

In addition to the Minimum Viable Solution, the ideal doc improvement would:

1. Include in every module page all APIs gated behind disabled features, where it explicitly says for each one "this fn/struct/enum/trait is only available when the FEATURE is enabled. It is currently disabled." To avoid clutter all disabled APIs could be separated out into the bottom of module doc page in a "disabled features" section, or collapsed by default, or something like that.

2. Provide a page (or section) for every feature that links to every item that feature enables. Cross link everything. In the item documentation, always explicitly name any features that affect its availability (whether enabled or not) with cross links to the feature page.

Notes

Some dependencies, especially large frameworks, gate many APIs behind feature flags. For example I've had this issue with tokio and wasm-bindgen. It's difficult to discover feature-gated APIs, especially because without explicit doc strings from the author, there's no indication which APIs are feature gated.

Motivation for this feature request based on my work flow; I often have this flow:

1. Add a dependency,
2. cargo doc --open,
3. With the docs open in one window, write code in my editor.

Also:

• I make heavy use of the built-in browser search S hotkey.
• I often develop offline, such as during flights or commutes or spots with flaky/slow wifi, and can't always do online searches. Also, offline searches of cargo doc are always immediately relevant, whereas sometimes google searches include irrelevant results, ads, etc. Finally, offline searches are almost always faster, which helps speed up the study/write/review cycle.

[nrabulinski]

As a workaround for now to include feature-specific items in docs you can use doc_cfg feature.

Example:

#[cfg(any(feature = "foo", doc))]
#[doc(cfg(feature = "foo"))]
pub mod foo;

Will be displayed as:

EDIT: Instead of enabling doc_cfg feature globally you can also have it behind some cfg and compile the docs with, for example, cargo doc --cfg docsrs --all-features (that's how tokio does it)