Doctests that require a non-default feature, is it possible?

My crate has a non default feature required for a documentation example. I can’t figure out how to tell rustdoc that a certain feature needs to be enabled.

The main advantage is that the integration tests can be run with just cargo test, instead of just hanging indefinitely. Of course this would not test everything, but it’s better to test something than to hang in my opinion.

Hmmm. I’ve run into this when trying to provide a tested example for an optional feature; it would be lovely if a specific doctest could be tagged with a feature (set) somehow. I don’t think there’s any such option currently, but it would make a good feature request.

To take care of things like this you can manually use the doc attribute instead of relying on the /// sugar.

E.g.

/// Documentation relevant to all users.
/// Documentation relevant to all users.
/// Documentation relevant to all users.
///
/// Paragraph that mentions the feature.
#[cfg_attr(feature = "feature", doc = r##"
Paragraph that only appears when feature is enabled.

```
// doctest that only exists when the feature is enabled
```
"##)]

This technique was used in frunk for similar purposes.

P.S. in case it isn’t enabled in your default-features, don’t forget to enable the feature in [package.metadata.docs.rs] to make sure it appears in online documentation!

5 Likes

Thanks alot. That’s really helpful. I didn’t know about the existence of that way of writing docs.

In the mean time I have made the feature default and suggested people use “default-features = false”. I think I’ll sleep over it and reconsider the two options tomorrow.

I generally put

[package.metadata."docs.rs"]
all-features = true

in all my crates, hoping that gets all info out there.

@ExpHP That’s really neat. Just to clarify, does the documentation behind the cfg_attr flag get added to the existing comment, or does it replace it?

My mental model (which at least describes all of the behavior I’ve seen) is that every /// becomes its own #[doc = ...], and then they all get concatenated with an newline after each one. (so it does not replace them).

#[doc = "Documentation relevant to all users."]
#[doc = "Documentation relevant to all users."]
#[doc = "Documentation relevant to all users."]
#[doc = ""]
#[doc = "Paragraph that mentions the feature."]
#[cfg_attr(feature = "feature", doc = r##"
Paragraph that only appears when feature is enabled.

```
// doctest that only exists when the feature is enabled
```
"##)]

which becomes the following markdown

Documentation relevant to all users.
Documentation relevant to all users.
Documentation relevant to all users.

Paragraph that mentions the feature.

Paragraph that only appears when feature is enabled.

```
// doctest that only exists when the feature is enabled
```


(the precise rules for newlines matter if you’re trying to make a sentence appear conditionally rather than a paragraph)

P.S. I originally made a mistake in the previous post, the syntax is #[doc = $literal], not #[doc($literal)].

3 Likes

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.