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)

[spikespaz]

@nrabulinski I'm not understanding how to use this. I am trying to run this:

cargo doc --cfg docsrs --all-features

Where this is on one of the fields in my struct

    #[cfg_attr(docsrs, doc(cfg(feature = "unknown-fields")))]
    #[cfg(feature = "unknown-fields")]
    #[serde(flatten)]
    pub other_fields: serde_json::Value,

My Cargo.toml looks like this:

...

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

...

[features]
#default = ["unknown-fields"]
unknown-fields = []

The output I see is this:

❯ cargo doc --cfg docsrs --all-features
error: Found argument '--cfg' which wasn't expected, or isn't valid in this context

        If you tried to supply `--cfg` as a value rather than a flag, use `-- --cfg`

USAGE:
    cargo doc [OPTIONS]

For more information try --help

[epage]

@spikespaz I'd recommend checkout out argfile as its a fairly minimal crate that show cases that feature.

Things to note:

• Your lib.rs needs a #![cfg_attr(docsrs, feature(doc_auto_cfg))]
• --cfg docsrs needs to be passed to rustdoc, not cargo-doc

[epage]

I believe this issue is a duplicate of rust-lang/rust#96318, so I'm closing in favor of that. If there is something I missed in that analysis, feel free to speak up!

[nathan-at-least]

In addition to the doc_auto_cfg approach in the discussion above which can be used to provide full item docs with clear feature-gating indicators, I've also just discovered the document_features crate.

Those two pieces basically fulfill the spirit of my original post with this ticket! Love to see the ecosystem evolving like this.

Now my only desire is that it could all work more seamlessly out of the box, but we'll get there eventually. ;-)