diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md
index 4f7736d8df6..eb3e6a9dd50 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
 ///
 /// ```
@@ -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
@@ -106,7 +119,7 @@ our source code:
 ```text
     First, we set `x` to five:
 
-    ```rust
+    ```
     let x = 5;
     # let y = 6;
     # println!("{}", x + y);
@@ -114,7 +127,7 @@ our source code:
 
     Next, we set `y` to six:
 
-    ```rust
+    ```
     # let x = 5;
     let y = 6;
     # println!("{}", x + y);
@@ -122,7 +135,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 +149,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 +158,7 @@ error handling. Lets say you want the following,
 The problem is that `?` returns a `Result<T, E>` and test functions
 don't return anything so this will give a mismatched types error.
 
-```rust,ignore
+```ignore
 /// 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;
 /// # fn main() {
 /// 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
 not actually pass as a test.
 
-```rust
+```text
 /// ```no_run
 /// loop {
 ///     println!("Hello, world");
@@ -233,6 +246,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
diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs
index 8d913c75528..46b483325a2 100644
--- a/src/librustdoc/html/markdown.rs
+++ b/src/librustdoc/html/markdown.rs
@@ -911,10 +911,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;
         }
 
@@ -938,7 +936,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;