rustdoc: add an --edition flag to compile docs/doctests with a certain edition

[QuietMisdreavus]

To correspond with the 2018 edition, this adds a (currently unstable) --edition flag to rustdoc that makes it compile crates and doctests with the given edition. Once this lands, Cargo should be updated to pass this flag when the edition configuration option is given.

[rust-highfive]

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

[QuietMisdreavus]

r? @GuillaumeGomez

[GuillaumeGomez]

Once CI fixed, r=me.

[QuietMisdreavus]

@bors r=GuillaumeGomez

[bors]

📌 Commit 97aead0 has been approved by GuillaumeGomez

[bors]

⌛ Testing commit 97aead0 with merge 7ae31e9...

[bors]

💔 Test failed - status-travis

[TimNN]

Your PR failed on Travis. Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

The job exceeded the maximum time limit for jobs, and has been terminated.

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN.

[TimNN]

Your PR failed on Travis. Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

The job exceeded the maximum time limit for jobs, and has been terminated.

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN.

[kennytm]

@bors retry

3-hour timeout with x86_64-gnu-incremental.

[bors]

⌛ Testing commit 97aead0 with merge 06fa27d...

[wigy-opensource-developer]

What is missing to get this --edition flag onto stable? 1 year later I still need to use edition2018 on doctests in a crate that has edition="2018" in its Cargo.toml

[QuietMisdreavus]

This flag was stabilized alongside the 2018 edition in #54057. Cargo was passing it to rustdoc based on the Cargo.toml even earlier, starting in rust-lang/cargo#5299. What problems are you having?

[wigy-opensource-developer]

I have a doctest in an edition2018 crate like:

/// ```
/// # use crate::SomeStruct;
/// let s= SomeStruct::new();
/// ```

which did not find SomeStruct without adding the edition2018 flag explicitly to each doctest with a use crate::. So this should work without the flag since 1.32 latest?

[QuietMisdreavus]

Is that the entire doctest? Where is SomeStruct defined? Doctests are compiled as separate standalone binaries that link to their containing crate, so that exact example shouldn't work in either case. What error are you getting?

[wigy-opensource-developer]

I have compiled this minimal example, please run it with cargo test --doc:

#![allow(dead_code)]

pub struct SomeStruct {}

impl SomeStruct {
    /// Always returns true
    ///
    /// # Example
    ///
    /// ```edition2018
    /// # use crate::SomeStruct;
    /// let s = SomeStruct {};
    /// assert!(!s.foo());
    /// ```
    pub fn foo(&self) -> bool {
        true
    }
}

fn main() {}

Playground

Works fine without any errors. If I remove edition2018 from line 10 though, it fails with

error[E0432]: unresolved import `crate::SomeStruct`
 --> src/lib.rs:11:5
  |
3 | use crate::SomeStruct;
  |     ^^^^^^^^^^^^^^^^^ no `SomeStruct` in the root

If I go back to the edition2015 import format, that also fixes the error:

#![allow(dead_code)]

pub struct SomeStruct {}

impl SomeStruct {
    /// Always returns true
    ///
    /// # Example
    ///
    /// ```
    /// # use playground::SomeStruct;
    /// let s = SomeStruct {};
    /// assert!(s.foo());
    /// ```
    pub fn foo(&self) -> bool {
        true
    }
}

fn main() {}

Playground

[QuietMisdreavus]

Adding just edition2018 to the doctest actually causes the test to be ignored. Using the proper rust,edition2018 marker causes rustdoc to give the proper output:

$ rustdoc +stable --test f.rs --extern f=libf.rlib

running 1 test
test f.rs - SomeStruct::foo (line 10) ... FAILED

failures:

---- f.rs - SomeStruct::foo (line 10) stdout ----
error[E0432]: unresolved import `crate::SomeStruct`
 --> f.rs:11:5
  |
4 | use crate::SomeStruct;
  |     ^^^^^^^^^^^^^^^^^ no `SomeStruct` in the root

thread 'f.rs - SomeStruct::foo (line 10)' panicked at 'couldn't compile the test', src/librustdoc/test.rs:321:13
note: Run with `RUST_BACKTRACE=1` environment variable to display a backtrace.


failures:
    f.rs - SomeStruct::foo (line 10)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

Note that this is the same as taking the marker off the doctest and compiling with --edition=2018 passed directly to rustdoc:

$ rustdoc +stable --test f.rs --extern f=libf.rlib --edition=2018

running 1 test
test f.rs - SomeStruct::foo (line 10) ... FAILED

failures:

---- f.rs - SomeStruct::foo (line 10) stdout ----
error[E0432]: unresolved import `crate::SomeStruct`
 --> f.rs:11:5
  |
4 | use crate::SomeStruct;
  |     ^^^^^^^^^^^^^^^^^ no `SomeStruct` in the root

thread 'f.rs - SomeStruct::foo (line 10)' panicked at 'couldn't compile the test', src/librustdoc/test.rs:321:13
note: Run with `RUST_BACKTRACE=1` environment variable to display a backtrace.


failures:
    f.rs - SomeStruct::foo (line 10)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

For completeness, here is the output i received with your original sample:

$ rustdoc +stable --test f.rs --extern f=libf.rlib

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

[QuietMisdreavus]

The reason the test fails anyway is because the path crate::SomeStruct is not a valid path within that doctest - it's a separate crate, and SomeStruct is not declared within that "crate". You have to use the name of your original crate to properly reference SomeStruct.

EDIT: It's also worth noting that even playground::SomeStruct isn't a valid path for that doctest, since SomeStruct isn't even publicly exported in the source crate.

[wigy-opensource-developer]

Wow, that was a big oversight from me. 🙍‍♂️ Thanks for helping out. Is there a way to reduce sensitivity of doctest code to crate renames? I tried super:: without success, and it feels wrong to copy-paste the crate name all around its own crate. (the whole reason why edition 2018 introduced the crate path)

[QuietMisdreavus]

Not that i know of - since the doctests are meant to be example code listed in documentation, it fits that they would need to use the public name for everything. (And the setup of always being compiled as a standalone binary means that no "relative" path would work, either - the items in the original crate are always treated as an external crate.)