From ccc31ce3d5b07a8f3ba89e2c9b2306ac8c52d1f7 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 17 Aug 2017 22:11:41 +0200 Subject: [PATCH 1/3] set compile_fail flag stable --- src/librustdoc/html/markdown.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs index 2d14c02bf8a59..01e821033de82 100644 --- a/src/librustdoc/html/markdown.rs +++ b/src/librustdoc/html/markdown.rs @@ -909,10 +909,8 @@ impl LangString { let mut seen_rust_tags = false; let mut seen_other_tags = false; let mut data = LangString::all_false(); - let mut allow_compile_fail = false; let mut allow_error_code_check = false; if UnstableFeatures::from_environment().is_nightly_build() { - allow_compile_fail = true; allow_error_code_check = true; } @@ -936,7 +934,7 @@ impl LangString { data.test_harness = true; seen_rust_tags = !seen_other_tags || seen_rust_tags; } - "compile_fail" if allow_compile_fail => { + "compile_fail" => { data.compile_fail = true; seen_rust_tags = !seen_other_tags || seen_rust_tags; data.no_run = true; From 2ffcfeb82178384ceca818115d69c12a7257f712 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 22 Aug 2017 13:48:31 +0200 Subject: [PATCH 2/3] Add compile_fail documentation --- src/doc/rustdoc/src/documentation-tests.md | 28 +++++++++++++++------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index 4f7736d8df6bb..348fcd3b76920 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -5,7 +5,7 @@ that your tests are up to date and working. The basic idea is this: -```rust,ignore +```ignore /// # Examples /// /// ``` @@ -106,7 +106,7 @@ our source code: ```text First, we set `x` to five: - ```rust + ``` let x = 5; # let y = 6; # println!("{}", x + y); @@ -114,7 +114,7 @@ our source code: Next, we set `y` to six: - ```rust + ``` # let x = 5; let y = 6; # println!("{}", x + y); @@ -122,7 +122,7 @@ our source code: Finally, we print the sum of `x` and `y`: - ```rust + ``` # let x = 5; # let y = 6; println!("{}", x + y); @@ -136,7 +136,7 @@ explanation. Another case where the use of `#` is handy is when you want to ignore error handling. Lets say you want the following, -```rust,ignore +```ignore /// use std::io; /// let mut input = String::new(); /// io::stdin().read_line(&mut input)?; @@ -145,7 +145,7 @@ error handling. Lets say you want the following, The problem is that `?` returns a `Result` and test functions don't return anything so this will give a mismatched types error. -```rust,ignore +```ignore /// A doc test using ? /// /// ``` @@ -179,7 +179,7 @@ Here’s an example of documenting a macro: /// # } /// ``` /// -/// ```rust,should_panic +/// ```should_panic /// # #[macro_use] extern crate foo; /// # fn main() { /// panic_unless!(true == false, “I’m broken.”); @@ -224,7 +224,7 @@ only shows the part you care about. `should_panic` tells `rustdoc` that the code should compile correctly, but not actually pass as a test. -```rust +```text /// ```no_run /// loop { /// println!("Hello, world"); @@ -233,6 +233,18 @@ not actually pass as a test. # 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 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 From ebc195d292e959606e5bf01aa76a6b17ab4a1357 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 2 Sep 2017 22:03:12 +0200 Subject: [PATCH 3/3] Add precision for rustdoc block codes --- src/doc/rustdoc/src/documentation-tests.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index 348fcd3b76920..eb3e6a9dd5067 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -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`, 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. ## Pre-processing examples