rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests #48106
Conversation
(rust_highfive has picked a reviewer for you, use r? to override) |
ad8b975
to
d8d4c58
With #48095 merged, this is now open! |
Thanks! @bors: r+ |
|
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 19, 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 19, 2018
bors
added a commit
that referenced
this pull request
Feb 19, 2018
bors
added a commit
that referenced
this pull request
Feb 20, 2018
bors
added a commit
that referenced
this pull request
Feb 20, 2018
bors
added a commit
that referenced
this pull request
Feb 20, 2018
bors
added a commit
that referenced
this pull request
Feb 20, 2018
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(); } ```
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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
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:extern crate
statement in the test, if the test also uses the local crate name, it will automatically insert anextern crate cratename;
statement into the test.extern crate
statement, rustdoc will not automatically insert one, on the assumption that doing so would introduce a duplicate import.fn main
outside a comment, rustdoc will wrap the whole doctest in a generatedfn main
so it can be compiled.In short, whenever you write a doctest like this...
...rustdoc will turn it into (something like) this:
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 explicitextern crate
statement) to also manually include their ownfn 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 generatedfn main
. Now, we can just do the same withextern crate
s at the beginning, too, and get a much nicer experience.Now, the above example will be converted into this: