New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from Feb 22, 2018

Conversation

Projects
None yet
5 participants
@QuietMisdreavus
Member

QuietMisdreavus commented Feb 9, 2018

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:

  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...

//! 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

This comment has been minimized.

Collaborator

rust-highfive commented Feb 9, 2018

r? @GuillaumeGomez

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

@shepmaster

This comment has been minimized.

Member

shepmaster commented Feb 17, 2018

Gated on #48095

This PR is blocked pending #48095

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

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

@QuietMisdreavus

This comment has been minimized.

Member

QuietMisdreavus commented Feb 17, 2018

With #48095 merged, this is now open!

@GuillaumeGomez

This comment has been minimized.

Member

GuillaumeGomez commented Feb 18, 2018

Thanks!

@bors: r+

@bors

This comment has been minimized.

Contributor

bors commented Feb 18, 2018

📌 Commit d8d4c58 has been approved by GuillaumeGomez

Manishearth added a commit to Manishearth/rust that referenced this pull request Feb 19, 2018

Rollup merge of rust-lang#48106 - QuietMisdreavus:teleporting-crates,…
… 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();
}
```

bors added a commit that referenced this pull request Feb 19, 2018

Auto merge of #48348 - Manishearth:rollup, r=Manishearth
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:

Manishearth added a commit to Manishearth/rust that referenced this pull request Feb 19, 2018

Rollup merge of rust-lang#48106 - QuietMisdreavus:teleporting-crates,…
… 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();
}
```

bors added a commit that referenced this pull request Feb 19, 2018

Auto merge of #48350 - Manishearth:rollup, r=Manishearth
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:

bors added a commit that referenced this pull request Feb 19, 2018

Auto merge of #48350 - Manishearth:rollup, r=Manishearth
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:

bors added a commit that referenced this pull request Feb 20, 2018

Auto merge of #48350 - Manishearth:rollup, r=Manishearth
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:

bors added a commit that referenced this pull request Feb 20, 2018

Auto merge of #48350 - Manishearth:rollup, r=Manishearth
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:

bors added a commit that referenced this pull request Feb 20, 2018

Auto merge of #48350 - Manishearth:rollup, r=Manishearth
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:

bors added a commit that referenced this pull request Feb 20, 2018

Auto merge of #48350 - Manishearth:rollup, r=Manishearth
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:

bors added a commit that referenced this pull request Feb 20, 2018

Auto merge of #48350 - Manishearth:rollup, r=Manishearth
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:

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Feb 21, 2018

Rollup merge of rust-lang#48106 - QuietMisdreavus:teleporting-crates,…
… 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();
}
```

bors added a commit that referenced this pull request Feb 21, 2018

Auto merge of #48399 - GuillaumeGomez:rollup, r=GuillaumeGomez
Rollup of 12 pull requests

- Successful merges: #47379, #47833, #48106, #48198, #48314, #48325, #48335, #48352, #48354, #48360, #48382, #48397
- Failed merges:

bors added a commit that referenced this pull request Feb 22, 2018

Auto merge of #48399 - GuillaumeGomez:rollup, r=GuillaumeGomez
Rollup of 12 pull requests

- Successful merges: #47379, #47833, #48106, #48198, #48314, #48325, #48335, #48352, #48354, #48360, #48382, #48397
- Failed merges:

@bors bors merged commit d8d4c58 into rust-lang:master Feb 22, 2018

1 check passed

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

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

hawkw added a commit to hawkw/tokio that referenced this pull request Aug 24, 2018

Fix doctests failing on Rust 1.25.0
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment