are features never documented

RunAwayFrog, 9 months ago

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:

https://sh.itjust.works/pictrs/image/06f9b6d2-b682-4c95-8bd3-33281d369b6e.webp

Here is the view from inside a module:

https://sh.itjust.works/pictrs/image/895cdff4-49ad-4cc3-83b5-ba8c8ae6ea3e.webp

Here is the view from a function page:

https://sh.itjust.works/pictrs/image/48258d4c-13fc-4d3f-a44a-1a08f2856aaf.webp

This is also true for platform support. Take this extension trait from std:

https://sh.itjust.works/pictrs/image/8e8c6506-918c-4945-be31-08e97e05c7c8.webp

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.

pileghoff, 9 months ago

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

RunAwayFrog, 9 months ago

So, this is being worked on. But for now, that crate needs this line in lib.rs

<span style="color:#323232;">#![cfg_attr(docsrs, feature(doc_auto_cfg))]
</span>

And this line in Cargo.toml’s [package.metadata.docs.rs] section:

<span style="color:#323232;">rustdoc-args = ["--cfg", "docsrs"]
</span>

With these changes, feature gating will be displayed in the docs.

To replicate this locally:

<span style="color:#323232;">RUSTDOCFLAGS='--cfg docsrs' cargo doc --features=nightly,defmt,pender-callback,arch-cortex-m,executor-thread,executor-interrupt
</span>

pileghoff, 9 months ago

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?

RunAwayFrog, 9 months ago

are there any hurdles or other good reasons to not just adding this to every create?

I’m no expert. But my guess would be that many crate authors may simply not be aware of this feature. It wasn’t always there, and it’s still unstable. You would have to reach the “Unstable features” page of the rustdoc book to know about it.

Or maybe some know about it, but don’t want to use an unstable feature, or are just waiting for it to possibly automatically work without any modifications.

Of course, I would assume none of this applies to the embassy devs. That Cargo.toml file has a flavors field, which is something I’ve never seen before 😉 So, I’m assuming they are way more knowledgable (and up-to-date) about the Rust ecosystem than me.

snaggen, 9 months ago

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.

RunAwayFrog, 9 months ago

–all-features doesn’t work with that particular crate because two of the features conflict with each other. The features list in my command is the one used for docs.rs from the crate’s Cargo.toml.

hunger, 9 months ago

docs.rs/document-features/…/document_features/ helps to document features.

But yes, features are under-documented.

somegeek, 9 months ago

Yep. I guess that’s the case for now.

Vorpal, 9 months ago

A few crates do document this, but it is often missing indeed.

Sometimes I have seen it documented as comments in Cargo.toml as well.