Discovering APIs, Structs, etc that require enabled features

Often times, I find myself trying to evaluate whether I want to use a crate in a no_std environment. I'll go to their docs.rs page and find that there is a std feature and sometimes there's some vague note about limited functionality in no_std environments. In rustdoc, you can go looking at each individual Struct/Trait/Method/Function/etc and there will be a generated note indicating whether that particular Struct/Trait/Method/Function/etc is gated by a feature. This is inconvenient though since you have to go item by item to evaluate what is and isn't supported. Is there any way in rustdoc to be able to filter items that are tied to certain features? Does anyone else have tools/strategies to discover which apis are available without std?

Optimally, the crate should properly document the differences between #![no_std] and std-capable APIs. But you can always pull the crate in an empty test project, and run cargo doc --open to view the documentation for your crate and all its dependencies, with different feature sets enabled. It's not that convenient if you want to know the differences between std and #![no_std] APIs, but if you want to look just at #![no_std] it's good enough.

1 Like

In my specific situation, I'm looking for std vs no_std, but, in general, I think some way of filtering on features could be useful in docs hosted on docs.rs.

But you can always pull the crate in an empty test project, and run cargo doc --open to view the documentation for your crate and all its dependencies, with different feature sets enabled.

Thanks for this tip. Far from ideal, but its better than nothing

There is a nightly feature which will add little "only available with the std feature" annotations next to items behind a feature flag. The tokio docs are a good example of this.

This is what you would see when looking at the list of modules:

And this is the annotation you see when looking at an individual item:

The incantation I've used for this in the past is ![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] at the top of lib.rs, combines with telling docs.rs to compile your crate with --cfg=docsrs.

Unfortunately those features aren't stabilised, so crate authors need to explicitly opt into it.

2 Likes

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.