Skip to content
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

QuietMisdreavus
Copy link
Member

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
Copy link
Collaborator

r? @GuillaumeGomez

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

@shepmaster shepmaster added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 9, 2018
@shepmaster shepmaster added S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 17, 2018
@shepmaster
Copy link
Member

Gated on #48095

This PR is blocked pending #48095

@QuietMisdreavus 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
Copy link
Member Author

With #48095 merged, this is now open!

@QuietMisdreavus QuietMisdreavus added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. labels Feb 17, 2018
@GuillaumeGomez
Copy link
Member

Thanks!

@bors: r+

@bors
Copy link
Contributor

bors commented Feb 18, 2018

📌 Commit d8d4c58 has been approved by GuillaumeGomez

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 18, 2018
Manishearth added a commit to Manishearth/rust that referenced this pull request Feb 19, 2018
… 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 20, 2018
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Feb 21, 2018
… 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 22, 2018
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
@QuietMisdreavus QuietMisdreavus deleted the teleporting-crates branch February 23, 2018 21:25
hawkw added a commit to hawkw/tokio that referenced this pull request Aug 24, 2018
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
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants