Rollup of 6 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
 

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:

src/libcollections/vec.rs

@@ -1220,8 +1220,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/iter.rs

@@ -371,22 +371,21 @@ pub trait Iterator {
     ///
     /// # Implementation notes
     ///
-    /// It is not enforced that an iterator implementation yields the
-    /// declared number of elements. A buggy iterator may yield less
-    /// than the lower bound or more than the upper bound of elements.
+    /// It is not enforced that an iterator implementation yields the declared
+    /// number of elements. A buggy iterator may yield less than the lower bound
+    /// or more than the upper bound of elements.
     ///
-    /// `size_hint()` is primarily intended to be used for optimizations
-    /// such as reserving space for the elements of the iterator, but
-    /// must not be trusted to e.g. omit bounds checks in unsafe code.
-    /// An incorrect implementation of `size_hint()` should not lead to
-    /// memory safety violations.
+    /// `size_hint()` is primarily intended to be used for optimizations such as
+    /// reserving space for the elements of the iterator, but must not be
+    /// trusted to e.g. omit bounds checks in unsafe code. An incorrect
+    /// implementation of `size_hint()` should not lead to memory safety
+    /// violations.
     ///
-    /// That said, the implementation should provide a correct
-    /// estimation, because otherwise it would be a violation of the
-    /// trait's protocol.
+    /// That said, the implementation should provide a correct estimation,
+    /// because otherwise it would be a violation of the trait's protocol.
     ///
-    /// The default implementation returns `(0, None)` which is correct
-    /// for any iterator.
+    /// The default implementation returns `(0, None)` which is correct for any
+    /// iterator.
     ///
     /// # Examples
     ///
@@ -2750,7 +2749,7 @@ pub trait ExactSizeIterator: Iterator {
     /// implementation, you can do so. See the [trait-level] docs for an
     /// example.
     ///
-    /// This function has the same safety guarantees as [`size_hint()`]
+    /// This function has the same safety guarantees as the [`size_hint()`]
     /// function.
     ///
     /// [trait-level]: trait.ExactSizeIterator.html

src/libstd/path.rs

@@ -1013,6 +1013,21 @@ impl PathBuf {
     /// * if `path` has a root but no prefix (e.g. `\windows`), it
     ///   replaces everything except for the prefix (if any) of `self`.
     /// * if `path` has a prefix but no root, it replaces `self`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::PathBuf;
+    ///
+    /// let mut path = PathBuf::new();
+    /// path.push("/tmp");
+    /// path.push("file.bk");
+    /// assert_eq!(path, PathBuf::from("/tmp/file.bk"));
+    ///
+    /// // Pushing an absolute path replaces the current path
+    /// path.push("/etc/passwd");
+    /// assert_eq!(path, PathBuf::from("/etc/passwd"));
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn push<P: AsRef<Path>>(&mut self, path: P) {
         self._push(path.as_ref())