Allow adding a description for features

[luser]

There's an existing crates.io feature request requesting that crate pages list the features the crate provides. Unfortunately currently that would just be a list of feature names, since that's all that the manifest format allows. It would be nice if features were allowed to provide a description as well, like (to modify the example from the docs):

[package]
name = "awesome"

[features]
# The default set of optional packages. Most people will want to use these
# packages, but they are strictly optional. Note that `session` is not a package
# but rather another feature listed in this manifest.
default = ["jquery", "uglifier", "session"]

# A feature with no dependencies is used mainly for conditional compilation,
# like `#[cfg(feature = "go-faster")]`.
go-faster = { "description" = "Do awesome things faster", dependencies = [] }

# The `secure-password` feature depends on the bcrypt package. This aliasing
# will allow people to talk about the feature in a higher-level way and allow
# this package to add more requirements to the feature in the future.
[features.secure-password]
description = "Enable secure password support based on bcrypt"
dependencies = ["bcrypt"]

# Features can be used to reexport features of other packages. The `session`
# feature of package `awesome` will ensure that the `session` feature of the
# package `cookie` is also enabled.
[features.session]
description = "Enable session cookies"
dependencies = ["cookie/session"]

This has a lot of overlap with the implicit features RFC. Namely, it requires the proposed "verbose form" of specifying features in order to even have a place to put the description. Additionally, if that RFC were not implemented then we would also likely need to allow adding descriptions to optional dependencies, since they can currently be used as features.

[sanmai-NL]

Adding more user-facing metadata to the Cargo manifest concerns me.

1. What makes us so sure a simple short description, without any document markup, will be any clearer than the feature name itself?
2. How does the proposed facility influence maintainers in choosing clear feature names (even if verbose)?
3. How does this affect technical writers (whoever have this role), who have a tough job already covering all places where they need to maintain documentation (READMEs, API documentation, official websites, etc.)?
4. How does this address industry needs, e.g. those needs other than a context of OSS crates published and used between programmers? If a company releases a set of artifacts with different features enabled/disabled, having to copy the feature descriptions over from an internal Cargo manifest to product documentation would be an unneccessary DRY violation.

[tgross35]

I've created an RFC based around this, rust-lang/rfcs#3416. I tried to address some of the concerns listed above, but feedback is welcome there

[CAD97]

Prior art: #![doc = document_features!()] is a proc macro to render feature documentation in the rustdoc generated docs. It uses ## to attach "documentation comments" to the following feature/dependency and #! to put documentation at the top level between feature docs.

[epage]

Personally, I don't want to require format-preserving parses to extract non-syntactically meaningful comments as-if they were syntactically meaningful.

Most of the talk has been around adding a new field, reminiscent of package.description. The main question is whether it should be opaque like package.description or if we should specify it to be markdown with a summary line, like rustdoc.