RFC: Cargo feature descriptions

[tgross35]

Rendered

RFC for feature-documentation
RFC goals: add a way to write feature descriptions in Cargo.toml

This was split from #3416

[features]
# current configuration
foo = []
# Add a description to the feature
bar = { enables = ["foo"], doc = "simple docstring here"}

# Features can also be full tables if descriptions are longer
[features.qux]
enables = ["bar", "baz"]
doc = """
# qux

This could be a longer description of this feature
"""

This would resolve rust-lang/cargo#4956

[tgross35]

@rustbot label +t-cargo

[rustbot]

Error: Label t-cargo can only be set by Rust team members

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[epage]

@tgross35 thanks for the access. Definitely makes it handy for the more trivial feedback.

[epage]

Wanted to highlight this for discussion. My main interest is in being able to show summaries in cargo add. Might be good to reach out to @kornelski for what they have seen of how features are documented through the ecosystem as that might help show potential requirements.

[kornelski]

Package descriptions tend to use markdown `code` and *emphasis*. Rust devs really like using ` everywhere. Even rustc uses ` in terminal error messages.

Markdown's goal is to look fine even when displayed as plain text.

You could define it as the first line being for CLI help, and the rest for docs. Analogous to how rustdoc handles doc comments.

[weihanglo]

One of the issues is how rustdoc consumes the data. rust doc generally knows nothing about Cargo.toml. I would suggest taking #3123 as a reference to start a discussion on cargo-rustdoc integration of this. It doesn't need to be perfect but at least two teams should have some consensus.

[tgross35]

I did bring it up when I initially proposed this feature, https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Descriptions.20for.20feature.20flags and then opened a draft RFC suggesting that rustdoc accept JSON configuration, which Cargo could pass it #3421. That didn't get too much traction, though. I will start that discussion back up