Rollup of 7 pull requests

README.md

@@ -1,13 +1,9 @@
 # The Rust Programming Language
 
-Rust is a fast systems programming language that guarantees
-memory safety and offers painless concurrency ([no data races]).
-It does not employ a garbage collector and has minimal runtime overhead.
+This is the main source code repository for [Rust]. It contains the compiler, standard library,
+and documentation.
 
-This repo contains the code for the compiler (`rustc`), as well
-as standard libraries, tools and documentation for Rust.
-
-[no data races]: http://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html
+[Rust]: https://www.rust-lang.org
 
 ## Quick Start
 

mk/tests.mk

@@ -25,7 +25,8 @@ $(eval $(call RUST_CRATE,collectionstest))
 TEST_TARGET_CRATES = $(filter-out core rustc_unicode alloc_system \
 		     		  alloc_jemalloc,$(TARGET_CRATES)) \
 			collectionstest coretest
-TEST_DOC_CRATES = $(DOC_CRATES)
+TEST_DOC_CRATES = $(DOC_CRATES) arena flate fmt_macros getopts graphviz \
+                log rand rbml serialize syntax term test
 TEST_HOST_CRATES = $(filter-out rustc_typeck rustc_borrowck rustc_resolve \
 		   		rustc_trans rustc_lint,\
                      $(HOST_CRATES))

src/doc/trpl/dining-philosophers.md

@@ -232,7 +232,7 @@ also called a ‘vector’, and it’s a growable array type. We then use a
 [`for`][for] loop to iterate through the vector, getting a reference to each
 philosopher in turn.
 
-[for]: for-loops.html
+[for]: loops.html#for
 
 In the body of the loop, we call `p.eat()`, which is defined above:
 

src/doc/trpl/documentation.md

@@ -373,6 +373,36 @@ we can add the `#[macro_use]` attribute. Second, we’ll need to add our own
 `main()` as well. Finally, a judicious use of `#` to comment out those two
 things, so they don’t show up in the output.
 
+Another case where the use of `#` is handy is when you want to ignore
+error handling. Lets say you want the following,
+
+```rust,ignore
+/// use std::io;
+/// let mut input = String::new(); 
+/// try!(io::stdin().read_line(&mut input));
+```
+
+The problem is that `try!` returns a `Result<T, E>` and test functions
+don't return anything so this will give a mismatched types error.
+
+```rust,ignore
+/// A doc test using try!
+///
+/// ```
+/// use std::io;
+/// # fn foo() -> io::Result<()> {
+/// let mut input = String::new(); 
+/// try!(io::stdin().read_line(&mut input));
+/// # Ok(())
+/// # }
+/// ```
+# fn foo() {}
+```
+
+You can get around this by wrapping the code in a function. This catches
+and swallows the `Result<T, E>` when running tests on the docs. This
+pattern appears regularly in the standard library.
+
 ### Running documentation tests
 
 To run the tests, either:
@@ -590,6 +620,18 @@ You can control a few aspects of the HTML that `rustdoc` generates through the
 
 This sets a few different options, with a logo, favicon, and a root URL.
 
+### Configuring documentation tests
+
+You can also configure the way that `rustdoc` tests your documentation examples
+through the `#![doc(test(..))]` attribute.
+
+```rust
+#![doc(test(attr(allow(unused_variables), deny(warnings))))]
+```
+
+This allows unused variables within the examples, but will fail the test for any
+other lint warning thrown.
+
 ## Generation options
 
 `rustdoc` also contains a few other options on the command line, for further customization:

src/liballoc/lib.rs

@@ -70,7 +70,7 @@
        html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
        html_root_url = "https://doc.rust-lang.org/nightly/",
        issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
-       test(no_crate_inject))]
+       test(no_crate_inject, attr(allow(unused_variables), deny(warnings))))]
 #![no_std]
 #![cfg_attr(not(stage0), needs_allocator)]
 

src/libarena/lib.rs

@@ -28,7 +28,8 @@
 #![crate_type = "dylib"]
 #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
-       html_root_url = "https://doc.rust-lang.org/nightly/")]
+       html_root_url = "https://doc.rust-lang.org/nightly/",
+       test(no_crate_inject, attr(deny(warnings))))]
 
 #![feature(alloc)]
 #![feature(box_syntax)]

src/libcollections/binary_heap.rs

@@ -233,6 +233,7 @@ impl<T: Ord> BinaryHeap<T> {
     ///
     /// ```
     /// #![feature(binary_heap_extras)]
+    /// # #![allow(deprecated)]
     ///
     /// use std::collections::BinaryHeap;
     /// let heap = BinaryHeap::from_vec(vec![9, 1, 2, 7, 3, 2]);

src/libcollections/borrow.rs

@@ -72,6 +72,7 @@ impl<T> ToOwned for T where T: Clone {
 /// ```
 /// use std::borrow::Cow;
 ///
+/// # #[allow(dead_code)]
 /// fn abs_all(input: &mut Cow<[i32]>) {
 ///     for i in 0..input.len() {
 ///         let v = input[i];

src/libcollections/btree/set.rs

@@ -89,6 +89,7 @@ impl<T: Ord> BTreeSet<T> {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(unused_mut)]
     /// use std::collections::BTreeSet;
     ///
     /// let mut set: BTreeSet<i32> = BTreeSet::new();

src/libcollections/fmt.rs

@@ -150,6 +150,7 @@
 //! implement a method of the signature:
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! # use std::fmt;
 //! # struct Foo; // our custom type
 //! # impl fmt::Display for Foo {
@@ -174,7 +175,6 @@
 //! like:
 //!
 //! ```
-//! #![feature(fmt_flags)]
 //! use std::fmt;
 //!
 //! #[derive(Debug)]
@@ -288,6 +288,7 @@
 //! off, some example usage is:
 //!
 //! ```
+//! # #![allow(unused_must_use)]
 //! use std::fmt;
 //! use std::io::{self, Write};
 //!

src/libcollections/lib.rs

@@ -27,7 +27,7 @@
        html_root_url = "https://doc.rust-lang.org/nightly/",
        html_playground_url = "https://play.rust-lang.org/",
        issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
-       test(no_crate_inject))]
+       test(no_crate_inject, attr(allow(unused_variables), deny(warnings))))]
 
 #![allow(trivial_casts)]
 #![cfg_attr(test, allow(deprecated))] // rand

src/libcollections/slice.rs

@@ -852,6 +852,7 @@ pub trait SliceConcatExt<T: ?Sized> {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(deprecated)]
     /// assert_eq!(["hello", "world"].connect(" "), "hello world");
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]

src/libcollections/str.rs

@@ -298,7 +298,7 @@ impl str {
     /// done by `.chars()` or `.char_indices()`.
     ///
     /// ```
-    /// #![feature(str_char, core)]
+    /// #![feature(str_char)]
     ///
     /// use std::str::CharRange;
     ///
@@ -358,7 +358,7 @@ impl str {
     /// done by `.chars().rev()` or `.char_indices()`.
     ///
     /// ```
-    /// #![feature(str_char, core)]
+    /// #![feature(str_char)]
     ///
     /// use std::str::CharRange;
     ///
@@ -634,6 +634,7 @@ impl str {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(deprecated)]
     /// let four_lines = "foo\r\nbar\n\r\nbaz";
     /// let v: Vec<&str> = four_lines.lines_any().collect();
     ///
@@ -643,6 +644,7 @@ impl str {
     /// Leaving off the trailing character:
     ///
     /// ```
+    /// # #![allow(deprecated)]
     /// let four_lines = "foo\r\nbar\n\r\nbaz\n";
     /// let v: Vec<&str> = four_lines.lines_any().collect();
     ///
@@ -1179,8 +1181,6 @@ impl str {
     /// # Examples
     ///
     /// ```
-    /// #![feature(str_match_indices)]
-    ///
     /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
     /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
     ///
@@ -1216,8 +1216,6 @@ impl str {
     /// # Examples
     ///
     /// ```
-    /// #![feature(str_match_indices)]
-    ///
     /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
     /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
     ///

src/libcollections/string.rs

@@ -55,6 +55,7 @@ impl String {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(unused_mut)]
     /// let mut s = String::new();
     /// ```
     #[inline]
@@ -73,6 +74,20 @@ impl String {
     ///
     /// ```
     /// let mut s = String::with_capacity(10);
+    ///
+    /// // The String contains no chars, even though it has capacity for more
+    /// assert_eq!(s.len(), 0);
+    ///
+    /// // These are all done without reallocating...
+    /// let cap = s.capacity();
+    /// for i in 0..10 {
+    ///     s.push('a');
+    /// }
+    ///
+    /// assert_eq!(s.capacity(), cap);
+    ///
+    /// // ...but this may make the vector reallocate
+    /// s.push('a');
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]

src/libcollections/vec.rs

@@ -242,6 +242,7 @@ impl<T> Vec<T> {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(unused_mut)]
     /// let mut vec: Vec<i32> = Vec::new();
     /// ```
     #[inline]
@@ -1220,8 +1221,7 @@ impl<T> FromIterator<T> for Vec<T> {
         // expanded on this iteration in every case when the iterable is not
         // empty, but the loop in extend_desugared() is not going to see the
         // vector being full in the few subsequent loop iterations.
-        // So we get better branch prediction and the possibility to
-        // construct the vector with initial estimated capacity.
+        // So we get better branch prediction.
         let mut iterator = iterable.into_iter();
         let mut vector = match iterator.next() {
             None => return Vec::new(),

src/libcore/cell.rs

@@ -76,6 +76,7 @@
 //! a trait method that was originally defined to take `&self`.
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! use std::cell::RefCell;
 //!
 //! struct Graph {
@@ -125,6 +126,7 @@
 //! }
 //!
 //! struct RcBox<T> {
+//! # #[allow(dead_code)]
 //!     value: T,
 //!     refcount: Cell<usize>
 //! }
@@ -776,6 +778,7 @@ impl<'b, T: ?Sized> DerefMut for RefMut<'b, T> {
 /// use std::cell::UnsafeCell;
 /// use std::marker::Sync;
 ///
+/// # #[allow(dead_code)]
 /// struct NotThreadSafe<T> {
 ///     value: UnsafeCell<T>,
 /// }

src/libcore/cmp.rs

@@ -140,8 +140,6 @@ impl Ordering {
     /// This method can be used to reverse a comparison:
     ///
     /// ```
-    /// use std::cmp::Ordering;
-    ///
     /// let mut data: &mut [_] = &mut [2, 10, 5, 8];
     ///
     /// // sort the array from largest to smallest.
@@ -263,8 +261,6 @@ pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
     /// # Examples
     ///
     /// ```
-    /// use std::cmp::Ordering;
-    ///
     /// let result = 1.0 < 2.0;
     /// assert_eq!(result, true);
     ///

src/libcore/default.rs

@@ -15,6 +15,7 @@
 //! that define a set of options:
 //!
 //! ```
+//! # #[allow(dead_code)]
 //! struct SomeOptions {
 //!     foo: i32,
 //!     bar: f32,
@@ -24,6 +25,7 @@
 //! How can we define some default values? You can use `Default`:
 //!
 //! ```
+//! # #[allow(dead_code)]
 //! #[derive(Default)]
 //! struct SomeOptions {
 //!     foo: i32,
@@ -40,6 +42,7 @@
 //! If you have your own type, you need to implement `Default` yourself:
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! enum Kind {
 //!     A,
 //!     B,
@@ -66,6 +69,7 @@
 //! If you want to override a particular option, but still retain the other defaults:
 //!
 //! ```
+//! # #[allow(dead_code)]
 //! # #[derive(Default)]
 //! # struct SomeOptions {
 //! #     foo: i32,
@@ -88,6 +92,7 @@ use marker::Sized;
 /// # Examples
 ///
 /// ```
+/// # #[allow(dead_code)]
 /// #[derive(Default)]
 /// struct SomeOptions {
 ///     foo: i32,
@@ -114,6 +119,7 @@ pub trait Default: Sized {
     /// Making your own:
     ///
     /// ```
+    /// # #[allow(dead_code)]
     /// enum Kind {
     ///     A,
     ///     B,

src/libcore/hash/mod.rs

@@ -45,6 +45,7 @@
 //!
 //! struct Person {
 //!     id: u32,
+//! # #[allow(dead_code)]
 //!     name: String,
 //!     phone: u64,
 //! }

src/libcore/intrinsics.rs

@@ -334,6 +334,7 @@ extern "rust-intrinsic" {
     /// use std::mem;
     /// use std::ptr;
     ///
+    /// # #[allow(dead_code)]
     /// fn swap<T>(x: &mut T, y: &mut T) {
     ///     unsafe {
     ///         // Give ourselves some scratch space to work with
@@ -372,6 +373,7 @@ extern "rust-intrinsic" {
     /// ```
     /// use std::ptr;
     ///
+    /// # #[allow(dead_code)]
     /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
     ///     let mut dst = Vec::with_capacity(elts);
     ///     dst.set_len(elts);