Auto merge of #43949 - GuillaumeGomez:compile_fail_stable, r=alexcrichton
Compile fail stable Since #30726, we never made the `compile_fail` flag nor the error code check stable. I think it's time to change this fact. r? @alexcrichton
This commit is contained in:
commit
fd4bef54ab
|
@ -5,7 +5,7 @@ that your tests are up to date and working.
|
||||||
|
|
||||||
The basic idea is this:
|
The basic idea is this:
|
||||||
|
|
||||||
```rust,ignore
|
```ignore
|
||||||
/// # Examples
|
/// # Examples
|
||||||
///
|
///
|
||||||
/// ```
|
/// ```
|
||||||
|
@ -16,6 +16,19 @@ The basic idea is this:
|
||||||
The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
|
The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
|
||||||
running `rustdoc --test foo.rs` will extract this example, and then run it as a test.
|
running `rustdoc --test foo.rs` will extract this example, and then run it as a test.
|
||||||
|
|
||||||
|
Please note that by default, if no language is set for the block code, `rustdoc`
|
||||||
|
assumes it is `Rust` code. So the following:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
let x = 5;
|
||||||
|
```
|
||||||
|
|
||||||
|
is strictly equivalent to:
|
||||||
|
|
||||||
|
```
|
||||||
|
let x = 5;
|
||||||
|
```
|
||||||
|
|
||||||
There's some subtlety though! Read on for more details.
|
There's some subtlety though! Read on for more details.
|
||||||
|
|
||||||
## Pre-processing examples
|
## Pre-processing examples
|
||||||
|
@ -106,7 +119,7 @@ our source code:
|
||||||
```text
|
```text
|
||||||
First, we set `x` to five:
|
First, we set `x` to five:
|
||||||
|
|
||||||
```rust
|
```
|
||||||
let x = 5;
|
let x = 5;
|
||||||
# let y = 6;
|
# let y = 6;
|
||||||
# println!("{}", x + y);
|
# println!("{}", x + y);
|
||||||
|
@ -114,7 +127,7 @@ our source code:
|
||||||
|
|
||||||
Next, we set `y` to six:
|
Next, we set `y` to six:
|
||||||
|
|
||||||
```rust
|
```
|
||||||
# let x = 5;
|
# let x = 5;
|
||||||
let y = 6;
|
let y = 6;
|
||||||
# println!("{}", x + y);
|
# println!("{}", x + y);
|
||||||
|
@ -122,7 +135,7 @@ our source code:
|
||||||
|
|
||||||
Finally, we print the sum of `x` and `y`:
|
Finally, we print the sum of `x` and `y`:
|
||||||
|
|
||||||
```rust
|
```
|
||||||
# let x = 5;
|
# let x = 5;
|
||||||
# let y = 6;
|
# let y = 6;
|
||||||
println!("{}", x + y);
|
println!("{}", x + y);
|
||||||
|
@ -136,7 +149,7 @@ explanation.
|
||||||
Another case where the use of `#` is handy is when you want to ignore
|
Another case where the use of `#` is handy is when you want to ignore
|
||||||
error handling. Lets say you want the following,
|
error handling. Lets say you want the following,
|
||||||
|
|
||||||
```rust,ignore
|
```ignore
|
||||||
/// use std::io;
|
/// use std::io;
|
||||||
/// let mut input = String::new();
|
/// let mut input = String::new();
|
||||||
/// io::stdin().read_line(&mut input)?;
|
/// io::stdin().read_line(&mut input)?;
|
||||||
|
@ -145,7 +158,7 @@ error handling. Lets say you want the following,
|
||||||
The problem is that `?` returns a `Result<T, E>` and test functions
|
The problem is that `?` returns a `Result<T, E>` and test functions
|
||||||
don't return anything so this will give a mismatched types error.
|
don't return anything so this will give a mismatched types error.
|
||||||
|
|
||||||
```rust,ignore
|
```ignore
|
||||||
/// A doc test using ?
|
/// A doc test using ?
|
||||||
///
|
///
|
||||||
/// ```
|
/// ```
|
||||||
|
@ -179,7 +192,7 @@ Here’s an example of documenting a macro:
|
||||||
/// # }
|
/// # }
|
||||||
/// ```
|
/// ```
|
||||||
///
|
///
|
||||||
/// ```rust,should_panic
|
/// ```should_panic
|
||||||
/// # #[macro_use] extern crate foo;
|
/// # #[macro_use] extern crate foo;
|
||||||
/// # fn main() {
|
/// # fn main() {
|
||||||
/// panic_unless!(true == false, “I’m broken.”);
|
/// panic_unless!(true == false, “I’m broken.”);
|
||||||
|
@ -224,7 +237,7 @@ only shows the part you care about.
|
||||||
`should_panic` tells `rustdoc` that the code should compile correctly, but
|
`should_panic` tells `rustdoc` that the code should compile correctly, but
|
||||||
not actually pass as a test.
|
not actually pass as a test.
|
||||||
|
|
||||||
```rust
|
```text
|
||||||
/// ```no_run
|
/// ```no_run
|
||||||
/// loop {
|
/// loop {
|
||||||
/// println!("Hello, world");
|
/// println!("Hello, world");
|
||||||
|
@ -233,6 +246,18 @@ not actually pass as a test.
|
||||||
# fn foo() {}
|
# fn foo() {}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
`compile_fail` tells `rustdoc` that the compilation should fail. If it
|
||||||
|
compiles, then the test will fail. However please note that code failing
|
||||||
|
with the current Rust release may work in a future release, as new features
|
||||||
|
are added.
|
||||||
|
|
||||||
|
```text
|
||||||
|
/// ```compile_fail
|
||||||
|
/// let x = 5;
|
||||||
|
/// x += 2; // shouldn't compile!
|
||||||
|
/// ```
|
||||||
|
```
|
||||||
|
|
||||||
The `no_run` attribute will compile your code, but not run it. This is
|
The `no_run` attribute will compile your code, but not run it. This is
|
||||||
important for examples such as "Here's how to retrieve a web page,"
|
important for examples such as "Here's how to retrieve a web page,"
|
||||||
which you would want to ensure compiles, but might be run in a test
|
which you would want to ensure compiles, but might be run in a test
|
||||||
|
|
|
@ -911,10 +911,8 @@ impl LangString {
|
||||||
let mut seen_rust_tags = false;
|
let mut seen_rust_tags = false;
|
||||||
let mut seen_other_tags = false;
|
let mut seen_other_tags = false;
|
||||||
let mut data = LangString::all_false();
|
let mut data = LangString::all_false();
|
||||||
let mut allow_compile_fail = false;
|
|
||||||
let mut allow_error_code_check = false;
|
let mut allow_error_code_check = false;
|
||||||
if UnstableFeatures::from_environment().is_nightly_build() {
|
if UnstableFeatures::from_environment().is_nightly_build() {
|
||||||
allow_compile_fail = true;
|
|
||||||
allow_error_code_check = true;
|
allow_error_code_check = true;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -938,7 +936,7 @@ impl LangString {
|
||||||
data.test_harness = true;
|
data.test_harness = true;
|
||||||
seen_rust_tags = !seen_other_tags || seen_rust_tags;
|
seen_rust_tags = !seen_other_tags || seen_rust_tags;
|
||||||
}
|
}
|
||||||
"compile_fail" if allow_compile_fail => {
|
"compile_fail" => {
|
||||||
data.compile_fail = true;
|
data.compile_fail = true;
|
||||||
seen_rust_tags = !seen_other_tags || seen_rust_tags;
|
seen_rust_tags = !seen_other_tags || seen_rust_tags;
|
||||||
data.no_run = true;
|
data.no_run = true;
|
||||||
|
|
Loading…
Reference in New Issue