[rustdoc] Add new --feature-documentation command line option

[GuillaumeGomez]

Now that rust-lang/rfcs#3485 is about to be merged, I think it's time for rustdoc to implement its part as well.

It allows to add documentation for features (from cfg(feature = "...")).

This PR is very much up to debate on all aspects (starting with the name of the CLI option). Here are a few things that I think should be discussed:

• Should we add the possibility to show which features a feature is enabling?
  • If so, should it be a different CLI option or should we update this one to take more complex input? (JSON for example?)
• For now, it doesn't support intra-doc links. Should it?
  • If so, how to implement it considering it will not go through rustc?
• I think we should only to (intra-doc) link to features. For once, this should be easy... as long as it's in the same crate, otherwise, no clue. :')

TODO: Add test/rustdoc-ui tests once the CLI and what it should look like is agreed upon.

Your input is very welcome too @rust-lang/cargo!

r? @rust-lang/rustdoc

[rustbot]

Some changes occurred in HTML/CSS/JS.

cc @lolbinarycat

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @Enselic, @obi1kenobi

[rust-log-analyzer]

The job aarch64-gnu-llvm-21-2 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

[epage]

Should this be specific to features or generalized to any cfg or cfg value?

[weihanglo]

Do we want to make room for future possibilities like unstable and deprecated features, as well as feature visibility (public/internal)?

Also, do we want to show optionality, default features, and enabled by / will enable?

[epage]

For visibility, we could hack tha into cargo doc and only forward when --document-private-items is present. Granted, if there are visibility badges, that won't be shown.

[tgross35]

I no longer think my old rustdoc config RFC is the right path (though I still like parts of it), but I do think what I proposed for the CLI could be reasonable https://github.com/tgross35/rfcs/blob/rustdoc-cargo-config/text/0000-rustdoc-cargo-configuration.md#changes-to-rustdoc. Basically just forward the Cargo.toml representation:

--config-json '{
    "features": {
        "foo": {},
        "bar":{ "doc": "This feature gives access to the `X` struct", "enables": ["foo"] }
    }
}'`

Which leaves room for things like visibility and deprecation, and also gives rustdoc the bar->foo feature implication that may be nice to display somehow.

I'm just not sure it's worth figuring out a way to encode this info with separate CLI arguments when this is pretty much never going to be written by hand anyway.

[GuillaumeGomez]

Should this be specific to features or generalized to any cfg or cfg value?

Just in case, this is about cfg(feature = "..."). So only for feature. The cfg are already documented normally.

Do we want to make room for future possibilities like unstable and deprecated features, as well as feature visibility (public/internal)?

If we accept JSON as input, I suppose we can without too much problem.

Also, do we want to show optionality, default features, and enabled by / will enable?

That was part of the list of unresolved questions. I think we should provide both "enabled by"/"will enable". The "enabled by" can be computed from "will enable" tough.

For visibility, we could hack tha into cargo doc and only forward when --document-private-items is present. Granted, if there are visibility badges, that won't be shown.

I think we should always display features. However, would be nice to have "hidden" features too.

@tgross35 I like this approach too as it would allow cargo and rustdoc to share a crate for the validation. It would also allow to have an extensible content if more information is added later.

[epage]

Should this be specific to features or generalized to any cfg or cfg value?

Just in case, this is about cfg(feature = "..."). So only for feature. The cfg are already documented normally.

My idea was about

1. avoiding cargo-specifics in a general rust interface (unlike the cli, rendering has few compatibility guarantees, so that can do what it wants)
2. Some projects have other --cfg inputs to document
3. we want to add another form of cargo cfg input and having the interface general allows us to use it without getting yet another flag

[GuillaumeGomez]

My idea was about

1. avoiding cargo-specifics in a general rust interface (unlike the cli, rendering has few compatibility guarantees, so that can do what it wants)

2. Some projects have other `--cfg` inputs to document

3. we want to add another form of cargo cfg input and having the interface general allows us to use it without getting yet another flag

Hum, fair. Not sure if we want to include these cfg though as it could potentially interfere with existing ones (can it actually? To be checked).

[notriddle]

avoiding cargo-specifics in a general rust interface

If that's what you're worried about, then why even provide structured data? A CLI option that adds an arbitrary Markdown file to the generated docs, including a link on the home page and rendering it with the same Rustdoc chrome that all.html has, would be maximally generic.

rustdoc --crate-name my_crate src/lib.rs ... --extra-page target/debug/my_crate/features.md

[epage]

avoiding cargo-specifics in a general rust interface

If that's what you're worried about, then why even provide structured data? A CLI option that adds an arbitrary Markdown file to the generated docs, including a link on the home page and rendering it with the same Rustdoc chrome that all.html has, would be maximally generic.

rustdoc --crate-name my_crate src/lib.rs ... **--extra-page target/debug/my_crate/features.md**

A lot could be done through that interface. I guess the question is if we want any additional features, like cfg tags on items being able to link to a documented cfg