Crate page should list the crate's Cargo "features"

[mbrubeck]

It's currently hard to discover optional features for a crate. It would be useful for crates.io to list these along with the dependencies. Unfortunately there's no way to declare docs or other metadata for a feature, so this will just have to be a flat list, but maybe more info can be added in the future.

[dhardy]

Crates.io automatically shows README.md contents, so features can be documented there. This is what rand does. Since this is more flexible than a flat list, I'd argue the issue is sufficiently well solved already (or it's just a crate doc issue)?

[Lonami]

@dhardy the problem with relying on the README.md is that it may more easily lead to inconsistencies in my opinion (i.e. a new feature was added but they forgot to update the README.md). Perhaps this is overkill, but how about detecting a # Features section in the README.md? Would that be possible/desirable? Anyway, a flat list should be better than nothing.

[dhardy]

I actually with you @Lonami, but have one caveat to add: Cargo considers any optional dependency a "feature", though sometimes these are not intended for use by end users.

Ideally there would be some way of annotating features with documentation in the Cargo.toml such that a documented list of features can be generated.

[Lonami]

TOML supports comments so perhaps if there's one above a feature it could be used as its description. But I don't think there's any visible standard on this.

[dancojocaru2000]

I actually with you @Lonami, but have one caveat to add: Cargo considers any optional dependency a "feature", though sometimes these are not intended for use by end users.

There are 2 possible solutions to this:

1. Just list all of them anyway. There's no real reason not to. Even if they're not intended for end-users, there shouldn't be any problem in seeing that they exist.
2. Focus on custom features, for example the following line from the example in The Cargo Book: secure-password = ["bcrypt"]

[nvzqz]

I would love this feature! It's frustrating trying to find a crate's feature set and having to hunt down its Cargo.toml.

I believe all features (including optional dependencies) should be listed on a crate's page. There should be a distinction between custom features and dependency features, which would be a good middle ground for @dhardy's concern about "internal" features. This list should also express what features get enabled by other features.

[Lonami]

Note that optional dependencies are listed like the rest of dependencies with the "optional" text following the dependency name. See for example https://crates.io/crates/tokio.

[zoechi]

I stumbled upon this with refinery, barrel, diesel.
The features change often with new versions and are therefore cumbersome to discover in GitHub.
They should be easily processable automatically instead of maintaining them in the README.md because they are listed in Cargo.toml https://github.com/diesel-rs/diesel/blob/master/diesel/Cargo.toml#L45-L60

[pravic]

lib.rs shows available features, by the way.