Document what features are required for feature-gated items

rust-lang / futures-rs

Zero-cost asynchronous programming in Rust

https://rust-lang.github.io/futures-rs/

Apache License 2.0

5.31k stars 609 forks source link

Document what features are required for feature-gated items #2807

Closed jwodder closed 7 months ago

jwodder commented 7 months ago

One way to document this would be to use doc(cfg(feature = ...))) as described at https://users.rust-lang.org/t/how-to-document-optional-features-in-api-docs/64577/3, but I don't know how that would work with the large amount of re-exporting this workspace does.

taiki-e commented 7 months ago

This has already been done (e.g., see https://docs.rs/futures-util/latest/futures_util/#modules), but there are some issues that it doesn't work well in the re-export (i.e. documentation of futures), and the scope of features with the same name is different in futures and futures-util. Some of these should be fixed automatically as a side effect of other work for 0.4 (https://github.com/rust-lang/futures-rs/pull/2804), but I would accept patches if you have ideas for improvements.