async-nats: lack of documentation for feature flags

[jaskij]

Observed behavior

I was not able to find documentation for feature flags for the async-nats crate.

Expected behavior

Relatively easy to find documentation on what features are enabled by each feature flag.

Server and client version

async-nats 0.34.0

Host environment

docs.rs

Steps to reproduce

Look around async_nats documentation and try finding information on feature flags. Or the README in this repository.

[jaskij]

Once again: your template doesn't have a field for comments.

I have default-features = false set on all my dependencies out of habit, to minimize transitive dependencies and speed up builds. Today's build failure from #1242 has prompted me to look for documentation on what exactly server_2_10 even is. That has led me to opening this issue.

[Jarema]

The feature flags are automatically documented https://docs.rs/crate/async-nats/latest/features

That page lists all the features, noting which are enables by default.

Additionally, at module list, if module requires a feature flag, it shows the feature badge next to it.

[jaskij]

What I'm asking for here is a short, high-level overview of the features in a visible place, like the README. One sentence, even less, just to tell me if I even care about a feature.

Looking around, there have been some discussions but I'm not sure if anything came out of them, except the document_features crate.

---

I'm well aware of the docs.rs list of feature flags, but it's just that - a list, not documentation. It even features this note:

There is very little structured metadata to build this page from currently. You should check the main library docs, readme, or Cargo.toml in case the author documented the features in them.

The module list is fine, but it's only for modules, while #[cfg(feature("something")] can appear anywhere in the code.

In my case, the feature I was looking at was server_2_10 - which does not enable a module, and I was unable to find a description for.

[Jarema]

Yeah, unfortunately, there is no great way to document features.

We will go with adding comments in Cargo.toml and pointing to those in README. That way it will be easier to track the changes.

Does that sound good enough for what you asked for?

[jaskij]

Does that sound good enough for what you asked for?

Absolutely, docs.rs even links to Cargo.toml as a possible place to look for that. Thank you very much.

Edit:

It's easy to get a version mismatch this way though. Your README linking to main in this repo, which could change since you published the version someone is using.

[Jarema]

I think I found a good enough solution that avoids drift between Readme and current released.

Closing. Feel free to reopen if you think that is not enough :).

Thanks for bringing this up!

[jaskij]

Looks good. Thank you.