I have a written a bit of rust by now, but one problem I always seem to encounter it that the features a create supports never seem to be documented. Neither what features are available, what they each do or which are default. Is that really the case, or am I missing something?
I constantly seem to include something from the docs, only to be told by the compiler that it does not exist, and then I have to open the source for the create to figure out if it’s hidden behind a feature flag.
Also, is it really true that I can’t disable a single feature from the default set, without having to copy the default list and manually removing it?
Yep. I guess that’s the case for now.
https://docs.rs/document-features/latest/document_features/ helps to document features.
But yes, features are under-documented.
I constantly seem to include something from the docs, only to be told by the compiler that it does not exist, and then I have to open the source for the create to figure out if it’s hidden behind a feature flag.
As others mentioned, the situation is not perfect. And you may need to check Cargo.toml. Maybe even the source.
But as for the quoted part above, the docs should definitely indicate if a part of the API is behind a feature. Let’s take rustix as an example.
Here is the module list:
Here is the view from inside a module:
Here is the view from a function page:
This is also true for platform support. Take this extension trait from std:
Now, it’s true that one could be navigating to method docs in the middle of a long doc page, where those indicators at the top may be missed. But that’s a UI issue. And it could be argued that repeating those indicators over and over would introduce too much clutter.
Is that always suppose to be shown? My counter example (the one that prompted this thread) is embassy_executor::Executor. When looking in the docs i dont see anywhere that its locked behind a feature flag, you have to look in the source
So, this is being worked on. But for now, that crate needs this line in lib.rs
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
And this line in Cargo.toml’s [package.metadata.docs.rs] section:
rustdoc-args = ["--cfg", "docsrs"]
With these changes, feature gating will be displayed in the docs.
To replicate this locally:
RUSTDOCFLAGS='--cfg docsrs' cargo doc --features=nightly,defmt,pender-callback,arch-cortex-m,executor-thread,executor-interrupt
Sadly, this does not seem to be the norm in my experience. I have not attemped to adding this myself, but I wanted to ask: are there any hurdles or other good reasons to not just adding this to every create? Why isn’t it the default?
Didn’t know about this, looking forward for this to be stabilized. But a comment on your command, it is easier to use --all-features instead of listing them all.
