rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests #48106

QuietMisdreavus · 2018-02-09T21:09:30Z

Gated on #48095 - I based the branch atop that so i could show off the change in one of its tests, the actual change in this PR is just the last commit

There are a handful of unfortunate assumptions in the way rustdoc processes extern crate statements in doctests:

In the absence of an extern crate statement in the test, if the test also uses the local crate name, it will automatically insert an extern crate cratename; statement into the test.
If the doctest does include an extern crate statement, rustdoc will not automatically insert one, on the assumption that doing so would introduce a duplicate import.
If a doctest does not have the substring fn main outside a comment, rustdoc will wrap the whole doctest in a generated fn main so it can be compiled.

In short, whenever you write a doctest like this...

//! extern crate my_crate;
//! my_crate::some_cool_thing();

...rustdoc will turn it into (something like) this:

fn main() {
extern crate my_crate;
my_crate::some_cool_thing();
}

This creates issues when compiled, because now my_crate isn't even properly in scope! This forces people who want to have multiple crates in their doctests (or an explicit extern crate statement) to also manually include their own fn main, so rustdoc doesn't put their imports in the wrong place.

This PR just taps into another processing step rustdoc does to doctests: Whenever you add an #![inner_attribute] to the beginning of a doctest, rustdoc will actually splice those out and put it before the generated fn main. Now, we can just do the same with extern crates at the beginning, too, and get a much nicer experience.

Now, the above example will be converted into this:

extern crate my_crate;
fn main() {
my_crate::some_cool_thing();
}

rust-highfive · 2018-02-09T21:09:42Z

r? @GuillaumeGomez

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

shepmaster · 2018-02-17T15:39:35Z

Gated on #48095

This PR is blocked pending #48095

QuietMisdreavus · 2018-02-17T22:53:42Z

With #48095 merged, this is now open!

GuillaumeGomez · 2018-02-18T21:16:04Z

Thanks!

@bors: r+

bors · 2018-02-18T21:16:05Z

📌 Commit d8d4c58 has been approved by GuillaumeGomez

… r=GuillaumeGomez rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests Gated on rust-lang#48095 - I based the branch atop that so i could show off the change in one of its tests, the actual change in this PR is just the last commit There are a handful of unfortunate assumptions in the way rustdoc processes `extern crate` statements in doctests: 1. In the absence of an `extern crate` statement in the test, if the test also uses the local crate name, it will automatically insert an `extern crate cratename;` statement into the test. 2. If the doctest *does* include an `extern crate` statement, rustdoc will not automatically insert one, on the assumption that doing so would introduce a duplicate import. 3. If a doctest does not have the substring `fn main` outside a comment, rustdoc will wrap the whole doctest in a generated `fn main` so it can be compiled. In short, whenever you write a doctest like this... ```rust //! extern crate my_crate; //! my_crate::some_cool_thing(); ``` ...rustdoc will turn it into (something like) this: ```rust fn main() { extern crate my_crate; my_crate::some_cool_thing(); } ``` This creates issues when compiled, because now `my_crate` isn't even properly in scope! This forces people who want to have multiple crates in their doctests (or an explicit `extern crate` statement) to also manually include their own `fn main`, so rustdoc doesn't put their imports in the wrong place. This PR just taps into another processing step rustdoc does to doctests: Whenever you add an `#![inner_attribute]` to the beginning of a doctest, rustdoc will actually splice those out and put it before the generated `fn main`. Now, we can just do the same with `extern crate`s at the beginning, too, and get a much nicer experience. Now, the above example will be converted into this: ```rust extern crate my_crate; fn main() { my_crate::some_cool_thing(); } ```

Rollup of 16 pull requests - Successful merges: #48082, #48083, #48084, #48106, #48123, #48125, #48157, #48185, #48197, #48198, #48206, #48208, #48221, #48258, #48314, #48335 - Failed merges:

… r=GuillaumeGomez rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests Gated on rust-lang#48095 - I based the branch atop that so i could show off the change in one of its tests, the actual change in this PR is just the last commit There are a handful of unfortunate assumptions in the way rustdoc processes `extern crate` statements in doctests: 1. In the absence of an `extern crate` statement in the test, if the test also uses the local crate name, it will automatically insert an `extern crate cratename;` statement into the test. 2. If the doctest *does* include an `extern crate` statement, rustdoc will not automatically insert one, on the assumption that doing so would introduce a duplicate import. 3. If a doctest does not have the substring `fn main` outside a comment, rustdoc will wrap the whole doctest in a generated `fn main` so it can be compiled. In short, whenever you write a doctest like this... ```rust //! extern crate my_crate; //! my_crate::some_cool_thing(); ``` ...rustdoc will turn it into (something like) this: ```rust fn main() { extern crate my_crate; my_crate::some_cool_thing(); } ``` This creates issues when compiled, because now `my_crate` isn't even properly in scope! This forces people who want to have multiple crates in their doctests (or an explicit `extern crate` statement) to also manually include their own `fn main`, so rustdoc doesn't put their imports in the wrong place. This PR just taps into another processing step rustdoc does to doctests: Whenever you add an `#![inner_attribute]` to the beginning of a doctest, rustdoc will actually splice those out and put it before the generated `fn main`. Now, we can just do the same with `extern crate`s at the beginning, too, and get a much nicer experience. Now, the above example will be converted into this: ```rust extern crate my_crate; fn main() { my_crate::some_cool_thing(); } ```

Rollup of 17 pull requests - Successful merges: #48052, #48072, #48082, #48083, #48084, #48106, #48123, #48157, #48185, #48197, #48198, #48206, #48208, #48221, #48258, #48314, #48335 - Failed merges:

… r=GuillaumeGomez rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests Gated on rust-lang#48095 - I based the branch atop that so i could show off the change in one of its tests, the actual change in this PR is just the last commit There are a handful of unfortunate assumptions in the way rustdoc processes `extern crate` statements in doctests: 1. In the absence of an `extern crate` statement in the test, if the test also uses the local crate name, it will automatically insert an `extern crate cratename;` statement into the test. 2. If the doctest *does* include an `extern crate` statement, rustdoc will not automatically insert one, on the assumption that doing so would introduce a duplicate import. 3. If a doctest does not have the substring `fn main` outside a comment, rustdoc will wrap the whole doctest in a generated `fn main` so it can be compiled. In short, whenever you write a doctest like this... ```rust //! extern crate my_crate; //! my_crate::some_cool_thing(); ``` ...rustdoc will turn it into (something like) this: ```rust fn main() { extern crate my_crate; my_crate::some_cool_thing(); } ``` This creates issues when compiled, because now `my_crate` isn't even properly in scope! This forces people who want to have multiple crates in their doctests (or an explicit `extern crate` statement) to also manually include their own `fn main`, so rustdoc doesn't put their imports in the wrong place. This PR just taps into another processing step rustdoc does to doctests: Whenever you add an `#![inner_attribute]` to the beginning of a doctest, rustdoc will actually splice those out and put it before the generated `fn main`. Now, we can just do the same with `extern crate`s at the beginning, too, and get a much nicer experience. Now, the above example will be converted into this: ```rust extern crate my_crate; fn main() { my_crate::some_cool_thing(); } ```

Rollup of 12 pull requests - Successful merges: #47379, #47833, #48106, #48198, #48314, #48325, #48335, #48352, #48354, #48360, #48382, #48397 - Failed merges:

Turns out there was an issue with doctest imports that was fixed in 1.26: rust-lang/rust#48106 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

rust-highfive assigned GuillaumeGomez Feb 9, 2018

shepmaster added S-waiting-on-review S-waiting-on-author and removed S-waiting-on-review labels Feb 9, 2018

shepmaster added S-blocked and removed S-waiting-on-author labels Feb 17, 2018

QuietMisdreavus added 2 commits Feb 9, 2018

move manual "extern crate" statements outside auto "fn main" in doctests

b3d6597

fix E0260 error index doctest

Loading status checks…

d8d4c58

QuietMisdreavus force-pushed the QuietMisdreavus:teleporting-crates branch from ad8b975 to d8d4c58 Feb 17, 2018

QuietMisdreavus changed the title ~~[wip] rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests~~ rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests Feb 17, 2018

QuietMisdreavus added S-waiting-on-review and removed S-blocked labels Feb 17, 2018

bors added S-waiting-on-bors and removed S-waiting-on-review labels Feb 18, 2018

Manishearth mentioned this pull request Feb 19, 2018

Rollup of 16 pull requests #48348

Closed

Manishearth mentioned this pull request Feb 19, 2018

Rollup of 17 pull requests #48350

Closed

GuillaumeGomez mentioned this pull request Feb 21, 2018

Rollup of 12 pull requests #48399

Merged

bors merged commit d8d4c58 into rust-lang:master Feb 22, 2018
1 check passed

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

QuietMisdreavus deleted the QuietMisdreavus:teleporting-crates branch Feb 23, 2018

QuietMisdreavus mentioned this pull request Mar 19, 2018

rustdoc: move #[macro_use] extern crate statements outside the generated main in doctests #49174

Closed

hawkw mentioned this pull request Aug 29, 2018

guide: add a testing section to the contributing guide tokio-rs/tokio#598

Merged

rust-lang / rust

rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests #48106

rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests #48106

QuietMisdreavus commented Feb 9, 2018

rust-highfive commented Feb 9, 2018

shepmaster commented Feb 17, 2018

QuietMisdreavus commented Feb 17, 2018

GuillaumeGomez commented Feb 18, 2018

bors commented Feb 18, 2018

rust-lang / rust

rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests #48106

rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests #48106

Conversation

QuietMisdreavus commented Feb 9, 2018

rust-highfive commented Feb 9, 2018

shepmaster commented Feb 17, 2018

QuietMisdreavus commented Feb 17, 2018

GuillaumeGomez commented Feb 18, 2018

bors commented Feb 18, 2018