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

3 files changed, 18 insertions, 13 deletions

diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs
index 4eef3323403..2cb7d527618 100644
--- a/src/libstd/num/f32.rs
+++ b/src/libstd/num/f32.rs
@@ -339,7 +339,8 @@ impl Round for f32 {
     /// The fractional part of the number, satisfying:
     ///
     /// ```rust
-    /// assert!(x == trunc(x) + fract(x))
+    /// let x = 1.65f32;
+    /// assert!(x == x.trunc() + x.fract())
     /// ```
     ///
     #[inline]
diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs
index 1668019409e..1f01c26ad76 100644
--- a/src/libstd/num/f64.rs
+++ b/src/libstd/num/f64.rs
@@ -357,7 +357,8 @@ impl Round for f64 {
     /// The fractional part of the number, satisfying:
     ///
     /// ```rust
-    /// assert!(x == trunc(x) + fract(x))
+    /// let x = 1.65f64;
+    /// assert!(x == x.trunc() + x.fract())
     /// ```
     ///
     #[inline]
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index c8c2ea8af81..0f81a5faac8 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -101,8 +101,7 @@ pub trait Unsigned: Num {}
 /// Times trait
 ///
 /// ```rust
-/// use num::Times;
-/// let ten = 10 as uint;
+/// let ten = 10u;
 /// let mut accum = 0;
 /// ten.times(|| { accum += 1; })
 /// ```
@@ -176,10 +175,10 @@ pub trait Round {
     /// # Example
     ///
     /// ```rust
-    /// assert_approx_eq!(1.3f32.round(), 1.0);
-    /// assert_approx_eq!((-1.3f32).round(), -1.0);
-    /// assert_approx_eq!(1.5f32.round(), 1.0);
-    /// assert_approx_eq!((-1.5f32).round(), -1.0);
+    /// assert_approx_eq!(1.3f32.trunc(), 1.0);
+    /// assert_approx_eq!((-1.3f32).trunc(), -1.0);
+    /// assert_approx_eq!(1.5f32.trunc(), 1.0);
+    /// assert_approx_eq!((-1.5f32).trunc(), -1.0);
     /// ```
     fn trunc(&self) -> Self;
 
@@ -188,10 +187,10 @@ pub trait Round {
     /// # Example
     ///
     /// ```rust
-    /// assert_approx_eq!(1.3f32.round(), 0.3);
-    /// assert_approx_eq!((-1.3f32).round(), -0.3);
-    /// assert_approx_eq!(1.5f32.round(), 0.5);
-    /// assert_approx_eq!((-1.5f32).round(), -0.5);
+    /// assert_approx_eq!(1.3f32.fract(), 0.3);
+    /// assert_approx_eq!((-1.3f32).fract(), -0.3);
+    /// assert_approx_eq!(1.5f32.fract(), 0.5);
+    /// assert_approx_eq!((-1.5f32).fract(), -0.5);
     /// ```
     fn fract(&self) -> Self;
 }
@@ -225,7 +224,9 @@ pub trait Algebraic {
 /// # Example
 ///
 /// ```rust
-/// let sixteen: float = num::pow(2.0, 4.0);
+/// use std::num;
+///
+/// let sixteen: f64 = num::pow(2.0, 4.0);
 /// assert_eq!(sixteen, 16.0);
 /// ```
 #[inline(always)] pub fn pow<T: Algebraic>(value: T, n: T) -> T { value.pow(&n) }
@@ -266,6 +267,8 @@ pub trait Trigonometric {
     /// # Example
     ///
     /// ```rust
+    /// use std::f32;
+    ///
     /// let y = 3f32.sqrt();
     /// let x = 1f32;
     /// assert_approx_eq!(y.atan2(&x), f32::consts::PI / 3f32);