How to doc-link to an item which isn't always available?

1

I have code like the following:

#[cfg(feature = "alloc")]
extern crate alloc;

/// Something to do with [`Vec<u8>`].
///
/// [`Vec<u8>`]: alloc::vec::Vec
trait Foo {}

The Foo trait exists unconditionally. However, when running cargo doc without the alloc feature, the intra-doc link to alloc::vec::Vec is broken because the extern crate alloc line is not compiled.

What is a good way to address this problem? A few details/things I've considered:

  • This isn't a problem for docs.rs because my Cargo.toml file has the following:
    [package.metadata.docs.rs]
all-features = true
  • I considered making it so that, when docs are being built, all features are enabled, but this could cause problems in the future if I introduce mutually-exclusive features, and it also makes all of my cfgs more complex.
  • Maybe I should just not care and only make sure that intra-doc links aren't broken when all features are enabled?

Has anyone run into this before? Is there a standard solution in the community?

2

Mutually-exclusive features are a problem of itself, since they will all add up when the library is a transitive dependency - user can end up with the unfixable erroneous configuration, because two of its direct dependencies require your crate with incompatible features. So this is something to avoid, anyway.

Could you explain what you mean here?

3

Ah that's a very good point.

Today:

#[cfg(feature = "alloc")]

With this change:

#[cfg(any(feature = "alloc", doc))]

It's not a major increase in complexity, but still :person_shrugging:

4

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.