Generate docs both with or without a feature

help
1

Is it able to generate docs to include both foo_a and foo_b with cargo doc?

#[cfg(feature = "foo")]
pub fn foo_a() {}

#[cfg(not(feature = "foo"))]
pub fn foo_b() {}

I understand that in the most idiomatic Rust style, "features" are meant to be additive, adding a feature shall not remove a functionality. However, in my real case, this really happens: In my crate, an algorithm can be speedup with a cache. Using that cache needs users to implement additional traits, while on the contrary, certain functionalities are not provided with the cache since it is too hard to implement. So I need my doc to include both the additional trait with cache feature and functionalities without cache feature. Is it possible? Or is there another way to control the functionalities? (I don't think runtime panicking in functionalities with cache enabled is a great solution).

2

I think the more idiomatic approach would be to have two structs with different names, one without cache and one with cache. You may not even need features, unless you want to use them to enable/disable dependencies.

2 Likes
3

You can use #[cfg(doc)] to enable code during doc generation.

#[cfg(any(doc. feature = "foo"))]
pub fn foo_a() {}

#[cfg(any(doc, not(feature = "foo")))]
pub fn foo_b() {}
1 Like