auto merge of #11120 : alexcrichton/rust/rustdoc-test, r=brson

This commit adds a `--test` flag to rustdoc to expose the ability to test code examples in doc strings. This work by using sundown's `lang` attribute to figure out how a code block should be tested. The format for this is:

```
1. ```rust
2. ```rust,ignore
3. ```rust,notest
4. ```rust,should_fail
```

Where `rust` means that rustdoc will attempt to test is, `ignore` means that it will not execute the test but it will compile it, `notest` means that rustdoc completely ignores it, and `should_fail` means that the test should fail. This commit also leverages `extra::test` for the testing harness in order to allow parallelization and whatnot.

I have fixed all existing code examples in libstd and libextra, but I have not made a pass through the crates in order to change code blocks to testable code blocks.

It may also be a questionable decision to require opting-in to a testable code block.

Finally, I kept our sugar in the doc suite to omit lines starting with `#` in documentation but still process them during tests.

Closes #2925

1 files changed, 3 insertions, 4 deletions

diff --git a/src/libstd/path/mod.rs b/src/libstd/path/mod.rs
index 53948dc8309..6488595ea4f 100644
--- a/src/libstd/path/mod.rs
+++ b/src/libstd/path/mod.rs
@@ -54,12 +54,11 @@ actually operates on the path; it is only intended for display.
 
 ```rust
 let mut path = Path::new("/tmp/path");
-debug!("path: {}", path.display());
+println!("path: {}", path.display());
 path.set_filename("foo");
 path.push("bar");
-debug!("new path: {}", path.display());
-let b = std::os::path_exists(&path);
-debug!("path exists: {}", b);
+println!("new path: {}", path.display());
+println!("path exists: {}", path.exists());
 ```
 
 */