(I see that this was suggested in the past, but that post has no comments and got auto-closed: [Pre-RFC] Rust and features (cargo) discoverability)
Currently there is no standard way to document features. At most, you may encounter an "Available on crate feature foo only." in the generated documentation of some type/function/trait you want to use - but if you need a feature that affects things a little deeper behind the scenes (like changing the behavior of some function which would exist with or without that feature) you have to scan the documentations yourself, not knowing where - if at all - the features the documented, hoping to find the name of the feature you need to enable in order to get the dependency to do what it should.
It would be much easier if features could have a description field. Just like dependencies can be either a table or a string - which is equivalent to a table with a single field named version - features too should support this duality, which would allow adding more fields to them:
[features]
foo = {
description = "Does this and that",
dependencies = ["bar", "baz"],
}
# Features with no decription can still be written the old way
bar = []
baz = []
These descriptions will be displayed when features are listed:
- The Feature flags tab in docs.rs would display the description.
- Commands like
cargo add, which prints the list of features the added crate supports, will also print the description of each feature. - Maybe a new command for just displaying the features with description without altering
Cargo.toml?
