add unit tests for rustdoc's processing of doctests #48095
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
r? @frewsxcv (rust_highfive has picked a reviewer for you, use r? to override) |
QuietMisdreavus
commented
Feb 9, 2018
| let expected = | ||
| "#![allow(unused)] | ||
| fn main() { | ||
| extern crate asdf; |
There was a problem hiding this comment.
I'd like to change this, but i felt it didn't fit in this PR, so i'll add it after this merges.
(EDIT: What i mean is, i want manual extern crate statements to go outside the automatic fn main wrapper.)
|
Seems good to me. 👍 |
|
@bors: r+ |
|
📌 Commit 7277993 has been approved by |
bors
added
the
S-waiting-on-bors
GuillaumeGomez
added a commit
to GuillaumeGomez/rust
that referenced
this pull request
Feb 16, 2018
…=GuillaumeGomez add unit tests for rustdoc's processing of doctests cc rust-lang#42018 There's a lot of things that rustdoc will do to massage doctests into something that can be compiled, and a lot of options that can be toggled to affect this. Hopefully this list of tests can show off that functionality. The first commit is slightly unrelated but doesn't touch public functionality, because i found that if you have a manual `fn main`, it adds an extra line break at the end, whereas it would trim this extra line break if it were putting a `fn main` in automatically. That first commit makes it trim out that whitespace ahead of time.
GuillaumeGomez
added a commit
to GuillaumeGomez/rust
that referenced
this pull request
Feb 17, 2018
…=GuillaumeGomez add unit tests for rustdoc's processing of doctests cc rust-lang#42018 There's a lot of things that rustdoc will do to massage doctests into something that can be compiled, and a lot of options that can be toggled to affect this. Hopefully this list of tests can show off that functionality. The first commit is slightly unrelated but doesn't touch public functionality, because i found that if you have a manual `fn main`, it adds an extra line break at the end, whereas it would trim this extra line break if it were putting a `fn main` in automatically. That first commit makes it trim out that whitespace ahead of time.
bors
added a commit
that referenced
this pull request
Feb 17, 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(); } ```
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(); } ```
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.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
cc #42018
There's a lot of things that rustdoc will do to massage doctests into something that can be compiled, and a lot of options that can be toggled to affect this. Hopefully this list of tests can show off that functionality.
The first commit is slightly unrelated but doesn't touch public functionality, because i found that if you have a manual
fn main, it adds an extra line break at the end, whereas it would trim this extra line break if it were putting afn mainin automatically. That first commit makes it trim out that whitespace ahead of time.