How do you discover crate features when using a new crate?

documentation
1

First, let me start by saying that rust doc and the cargo docs are generally great, and a lot of people put a lot of effort into documenting how to use their code.

When I start using a new crate, usually the first thing I do, therefore, is look at their docs.rs page, and I don't usually start by investigating their repository and trying to read their code.

However, inevitably I usually do have to go look at their repository, because afaict, rust docs does not generate any information about the crate's feature configuration.

Some projects, for example this one, has extensive documentation of their features in the main crate README.md: jwt_compact - Rust

Some projects document their "recommended" configuration which you can copy paste into your cargo toml, such as this one: GitHub - seanmonstar/warp: A super-easy, composable, web server framework for warp speeds.

However, those notes don't end up in the docs.rs for the project: warp - Rust

Some projects have a repo with a large workspace, so it may take some digging to find documentation around a particular crate's configuration.

Usually my experience has been that, unless there is something in the first rustdoc page for the crate, then I go to the repository for the crate, (which is usually but not always github), where I search for a README.md. If there's nothing mentioned there, then I look for a Cargo.toml and hope that there are # comments describing the features.

Cargo currently supports a cargo toml field [package.metadata.docs.rs], but this is used to customize the build flags and features used by docs.rs when it builds the documentation from the source code. It is not used to provide any information intended for the user to figure out how to configure your crate.

Question: Should there be a standard way to document what features your crate offers? Should rustdoc generate a summary of the different options, based on what appears in cargo.toml?

IMO it would be nice if docs.rs can tell me not only how to use the code, but how to configure the crate, at a particular release. That would mean that I would almost never have to navigate to the actual repository and try to find the released commit in order to figure out how to use the crate.

2

Never mind, I guess that this exists now! warp 0.3.5 - Docs.rs

3

Related:

  • cargo add will list features
  • I'd like us to have a cargo info which also lists features
  • There is an RFC for adding native feature descriptions
  • There is an unstable rustdoc feature to auto-label API items with their feature example
  • rustc 1.72.0 will now report in errors what features is needed when a build fails
1 Like
4

Tangentially related, I wish clap had, an option to generate a command to list which features were enabled when the binary was compiled.

5

Not quite something for clap to have baked in but other packages provide build-time features like that, like EmitBuilder in vergen - Rust

6

Also @kornel recently improved the website lib.rs by adding a new features page that incorporates useful additional information, in particular also documenting comments from Cargo.toml if present. E. g. here's the page for warp and here for jwt-compact.

2 Likes
7

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.