Doc example with feature dependency does not compile

[mordak]

A doc example which depends on a feature does not compile if the entire example is conditionally excluded.

Having the example conditionally compiled with a feature does not work if the feature is not enabled:

/// ```
/// #![cfg(feature = "foo")]
/// assert_eq!(1, 1);
/// ```
pub struct Foo;

Fails with:

error[E0601]: main function not found in crate rust_out
--> src/lib.rs:8:1
|
1 | / #![allow(unused)]
2 | | #![cfg(feature = "foo")]
3 | | fn main() { #[allow(non_snake_case)] fn doctest_main_src_lib_rs_9_0() {
4 | | assert_eq!(1, 1);
5 | | } doctest_main_src_lib_rs_9_0() }
| |________________________________^ consider adding a main function at the crate level

Adding a main() as suggested also does not work:

/// ```
/// #![cfg(feature = "foo")]
/// fn main() {
/// assert_eq!(1, 1);
/// }
/// ```
pub struct Foo;

Couldn't compile the test.
---- src/lib.rs - Foo (line 1) stdout ----
error[E0601]: main function not found in crate rust_out
--> src/lib.rs:1:1
|
1 | / #![allow(unused)]
2 | | #![cfg(feature = "foo")]
3 | | fn main() {
4 | | assert_eq!(1, 1);
5 | | }
| |_^ consider adding a main function at the crate level

I expected the example to compile like an empty example, which does work:

/// ```
/// ```
pub struct Baz;

Meta

Affects stable and nightly:

rustc --version --verbose:

rustc 1.52.1 (9bc8c42bb 2021-05-09)
binary: rustc
commit-hash: 9bc8c42bb2f19e745a63f3445f1ac248fb015e53
commit-date: 2021-05-09
host: x86_64-unknown-linux-gnu
release: 1.52.1
LLVM version: 12.0.0

rustc 1.54.0-nightly (5c0292654 2021-05-11)
binary: rustc
commit-hash: 5c029265465301fe9cb3960ce2a5da6c99b8dcf2
commit-date: 2021-05-11
host: x86_64-unknown-linux-gnu
release: 1.54.0-nightly
LLVM version: 12.0.1

[jonhoo]

For a bit more added context, this construction comes in very handy for doc-examples that explain how to use a particular feature when it's enabled on a type or method that isn't itself #[cfg].

And as always, cc @estebank.

[estebank]

In the meantime, the following will work:

/// ```
/// #[cfg(feature = "foo")]
/// fn main() {
/// assert_eq!(1, 1);
/// }
/// #[cfg(not(feature = "foo"))]
/// fn main() {}
/// ```
pub struct Foo;

[jonhoo]

Or, as we discovered:

/// ```
/// {} #[cfg(feature = "foo")]
/// fn main() {
/// assert_eq!(1, 1);
/// }
/// ```
pub struct Foo;
``

[Nemo157]

Rustdoc moves all outer attributes up to the root context, assuming they are intended to be crate attributes:

rust/src/librustdoc/doctest.rs

Lines 509 to 511 in 44ec846

	// Now push any outer attributes from the example, assuming they
	// are intended to be crate attributes.
	prog.push_str(&crate_attrs);

This is useful for supporting things like #![feature(...)], but it means your example is rewritten to

#![cfg(feature = "foo")]
fn main() {
    assert_eq!(1, 1);
}

and the entire generated crate is disabled when the feature is disabled, meaning there is no fn main for the test runner to call.

---

The variants you have actually running don't work though, features are not propagated into the examples when they are compiled, e.g. this does not fail under cargo test --doc --all-features:

EDIT: I was wrong, this example does work, but the alternative which applies the #[cfg] to an inner function doesn't, since it never calls the function (it somehow suppresses the fn main detection (ed: because it doesn't parse in item-context)) :

/// ```
/// {} #[cfg(feature = "foo")]
/// fn main() {
/// assert_eq!(1, 2);
/// }
/// ```
pub struct Foo;

In the past I have played around with a macro that removes examples based on currently active features. It'd probably be possible to do something similar that instead of removing examples inserts a warning that the example is relying on inactive features and tags it as no_run. And using a proc-macro-attribute could make for a more ergonomic API.

[mordak]

Oh, you are correct that the example with {} #[cfg(feature = "foo")] does not run, but it does compile so will identify compile errors in the example. We never noticed because all of these examples in our case have the no_run attribute on them so we don't run them anyway - we just wanted to compile test them. Thanks for pointing this out!