Rollup of 12 pull requests

src/doc/trpl/documentation.md

@@ -45,7 +45,7 @@ Rust keeps track of these comments, and uses them when generating
 documentation. This is important when documenting things like enums:
 
 ```rust
-/// The `Option` type. See [the module level documentation](../) for more.
+/// The `Option` type. See [the module level documentation](index.html) for more.
 enum Option<T> {
     /// No value
     None,
@@ -57,7 +57,7 @@ enum Option<T> {
 The above works, but this does not:
 
 ```rust,ignore
-/// The `Option` type. See [the module level documentation](../) for more.
+/// The `Option` type. See [the module level documentation](index.html) for more.
 enum Option<T> {
     None, /// No value
     Some(T), /// Some value `T`

src/doc/trpl/error-handling.md

@@ -182,7 +182,7 @@ analysis is the only way to get at the value stored inside an `Option<T>`. This
 means that you, as the programmer, must handle the case when an `Option<T>` is
 `None` instead of `Some(t)`.
 
-But wait, what about `unwrap` used in [`unwrap-double`](#code-unwrap-double)?
+But wait, what about `unwrap`,which we used [`previously`](#code-unwrap-double)?
 There was no case analysis there! Instead, the case analysis was put inside the
 `unwrap` method for you. You could define it yourself if you want:
 
@@ -211,7 +211,7 @@ that makes `unwrap` ergonomic to use. Unfortunately, that `panic!` means that
 
 ### Composing `Option<T>` values
 
-In [`option-ex-string-find`](#code-option-ex-string-find)
+In an [example from before](#code-option-ex-string-find),
 we saw how to use `find` to discover the extension in a file name. Of course,
 not all file names have a `.` in them, so it's possible that the file name has
 no extension. This *possibility of absence* is encoded into the types using

src/doc/trpl/guessing-game.md

@@ -99,9 +99,12 @@ use std::io;
 We’ll need to take user input, and then print the result as output. As such, we
 need the `io` library from the standard library. Rust only imports a few things
 by default into every program, [the ‘prelude’][prelude]. If it’s not in the
-prelude, you’ll have to `use` it directly.
+prelude, you’ll have to `use` it directly. There is also a second ‘prelude’, the
+[`io` prelude][ioprelude], which serves a similar function: you import it, and it
+imports a number of useful, `io`-related things.
 
 [prelude]: ../std/prelude/index.html
+[ioprelude]: ../std/io/prelude/index.html
 
 ```rust,ignore
 fn main() {

src/doc/trpl/primitive-types.md

@@ -162,13 +162,18 @@ A ‘slice’ is a reference to (or “view” into) another data structure. The
 useful for allowing safe, efficient access to a portion of an array without
 copying. For example, you might want to reference just one line of a file read
 into memory. By nature, a slice is not created directly, but from an existing
-variable. Slices have a length, can be mutable or not, and in many ways behave
-like arrays:
+variable binding. Slices have a defined length, can be mutable or immutable.
+
+## Slicing syntax
+
+You can use a combo of `&` and `[]` to create a slice from various things. The
+`&` indicates that slices are similar to references, and the `[]`s, with a
+range, let you define the length of the slice:
 
 ```rust
 let a = [0, 1, 2, 3, 4];
-let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3
 let complete = &a[..]; // A slice containing all of the elements in a
+let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3
 ```
 
 Slices have type `&[T]`. We’ll talk about that `T` when we cover

src/doc/trpl/testing.md

@@ -502,3 +502,5 @@ documentation tests: the `_0` is generated for the module test, and `add_two_0`
 for the function test. These will auto increment with names like `add_two_1` as
 you add more examples.
 
+We haven’t covered all of the details with writing documentation tests. For more,
+please see the [Documentation chapter](documentation.html)

src/doc/trpl/variable-bindings.md

@@ -1,7 +1,8 @@
 % Variable Bindings
 
 Virtually every non-'Hello World’ Rust program uses *variable bindings*. They
-look like this:
+bind some value to a name, so it can be used later. `let` is
+used to introduce a binding, just like this:
 
 ```rust
 fn main() {
@@ -13,10 +14,12 @@ Putting `fn main() {` in each example is a bit tedious, so we’ll leave that ou
 in the future. If you’re following along, make sure to edit your `main()`
 function, rather than leaving it off. Otherwise, you’ll get an error.
 
-In many languages, this is called a *variable*, but Rust’s variable bindings
-have a few tricks up their sleeves. For example the left-hand side of a `let`
-expression is a ‘[pattern][pattern]’, not just a variable name. This means we
-can do things like:
+# Patterns
+
+In many languages, a variable binding would be called a *variable*, but Rust’s
+variable bindings have a few tricks up their sleeves. For example the
+left-hand side of a `let` expression is a ‘[pattern][pattern]’, not just a
+variable name. This means we can do things like:
 
 ```rust
 let (x, y) = (1, 2);
@@ -29,6 +32,8 @@ of our minds as we go forward.
 
 [pattern]: patterns.html
 
+# Type annotations
+
 Rust is a statically typed language, which means that we specify our types up
 front, and they’re checked at compile time. So why does our first example
 compile? Well, Rust has this thing called ‘type inference’. If it can figure
@@ -63,6 +68,8 @@ Note the similarities between this annotation and the syntax you use with
 occasionally include them to help you understand what the types that Rust
 infers are.
 
+# Mutability
+
 By default, bindings are *immutable*. This code will not compile:
 
 ```rust,ignore
@@ -97,9 +104,11 @@ out of the scope of this guide. In general, you can often avoid explicit
 mutation, and so it is preferable in Rust. That said, sometimes, mutation is
 what you need, so it’s not verboten.
 
-Let’s get back to bindings. Rust variable bindings have one more aspect that
-differs from other languages: bindings are required to be initialized with a
-value before you're allowed to use them.
+# Initializing bindings
+
+Rust variable bindings have one more aspect that differs from other languages:
+bindings are required to be initialized with a value before you're allowed to
+use them.
 
 Let’s try it out. Change your `src/main.rs` file to look like this:
 
@@ -167,3 +176,77 @@ For now, we'll just stick to the default: integers aren't very complicated to
 print.
 
 [format]: ../std/fmt/index.html
+
+# Scope and shadowing
+
+Let’s get back to bindings. Variable bindings have a scope - they are
+constrained to live in a block they were defined in. A block is a collection
+of statements enclosed by `{` and `}`. Function definitions are also blocks!
+In the following example we define two variable bindings, `x` and `y`, which
+live in different blocks. `x` can be accessed from inside the `fn main() {}`
+block, while `y` can be accessed only from inside the inner block:
+
+```rust,ignore
+fn main() {
+    let x: i32 = 17;
+    {
+        let y: i32 = 3;
+        println!("The value of x is {} and value of y is {}", x, y);
+    }
+    println!("The value of x is {} and value of y is {}", x, y); // This won't work
+}
+```
+
+The first `println!` would print "The value of x is 17 and the value of y is
+3", but this example cannot be compiled successfully, because the second
+`println!` cannot access the value of `y`, since it is not in scope anymore.
+Instead we get this error:
+
+```bash
+$ cargo build
+   Compiling hello v0.1.0 (file:///home/you/projects/hello_world)
+main.rs:7:62: 7:63 error: unresolved name `y`. Did you mean `x`? [E0425]
+main.rs:7     println!("The value of x is {} and value of y is {}", x, y); // This won't work
+                                                                       ^
+note: in expansion of format_args!
+<std macros>:2:25: 2:56 note: expansion site
+<std macros>:1:1: 2:62 note: in expansion of print!
+<std macros>:3:1: 3:54 note: expansion site
+<std macros>:1:1: 3:58 note: in expansion of println!
+main.rs:7:5: 7:65 note: expansion site
+main.rs:7:62: 7:63 help: run `rustc --explain E0425` to see a detailed explanation
+error: aborting due to previous error
+Could not compile `hello`.
+
+To learn more, run the command again with --verbose.
+```
+
+Additionaly, variable bindings can be shadowed. This means that a later
+variable binding with the same name as another binding, that's currently in
+scope, will override the previous binding.
+
+```rust
+let x: i32 = 8;
+{
+    println!("{}", x); // Prints "8"
+    let x = 12;
+    println!("{}", x); // Prints "12"
+}
+println!("{}", x); // Prints "8"
+let x =  42;
+println!("{}", x); // Prints "42"
+```
+
+Shadowing and mutable bindings may appear as two sides of the same coin, but
+they are two distinct concepts that can't always be used interchangeably. For
+one, shadowing enables us to rebind a name to a value of a different type. It
+is also possible to change the mutability of a binding.
+
+```rust
+let mut x: i32 = 1;
+x = 7;
+let x = x; // x is now immutable and is bound to 7
+
+let y = 4;
+let y = "I can also be bound to text!"; // y is now of a different type
+```

src/libcollections/slice.rs

@@ -455,6 +455,8 @@ impl<T> [T] {
     /// the index `mid` itself) and the second will contain all
     /// indices from `[mid, len)` (excluding the index `len` itself).
     ///
+    /// # Panics
+    ///
     /// Panics if `mid > len`.
     ///
     /// # Examples

src/libcore/fmt/mod.rs

@@ -298,7 +298,7 @@ impl<'a> Display for Arguments<'a> {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -393,7 +393,7 @@ pub trait Debug {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -435,7 +435,7 @@ pub trait Display {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -482,7 +482,7 @@ pub trait Octal {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -530,7 +530,7 @@ pub trait Binary {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -578,7 +578,7 @@ pub trait LowerHex {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -624,7 +624,7 @@ pub trait UpperHex {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -668,7 +668,7 @@ pub trait Pointer {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -711,7 +711,7 @@ pub trait LowerExp {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///

src/libcore/iter.rs

@@ -1862,22 +1862,14 @@ impl<I> DoubleEndedIterator for Enumerate<I> where
 }
 
 /// An iterator with a `peek()` that returns an optional reference to the next element.
+#[derive(Clone)]
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Peekable<I: Iterator> {
     iter: I,
     peeked: Option<I::Item>,
 }
 
-impl<I: Iterator + Clone> Clone for Peekable<I> where I::Item: Clone {
-    fn clone(&self) -> Peekable<I> {
-        Peekable {
-            iter: self.iter.clone(),
-            peeked: self.peeked.clone(),
-        }
-    }
-}
-
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<I: Iterator> Iterator for Peekable<I> {
     type Item = I::Item;

src/libstd/io/mod.rs

@@ -370,6 +370,13 @@ fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize>
 /// throughout `std::io` take and provide types which implement the `Read`
 /// trait.
 ///
+/// Please note that each call to `read` may involve a system call, and
+/// therefore, using something that implements [`BufRead`][bufread], such as
+/// [`BufReader`][bufreader], will be more efficient.
+///
+/// [bufread]: trait.BufRead.html
+/// [bufreader]: struct.BufReader.html
+///
 /// # Examples
 ///
 /// [`File`][file]s implement `Read`:

src/libstd/path.rs

@@ -351,7 +351,6 @@ impl<'a> Prefix<'a> {
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub fn is_separator(c: char) -> bool {
-    use ascii::*;
     c.is_ascii() && is_sep_byte(c as u8)
 }
 
@@ -1292,7 +1291,7 @@ impl Path {
     /// use std::path::Path;
     ///
     /// let path_str = Path::new("foo.txt").to_str();
-    //// assert_eq!(path_str, Some("foo.txt"));
+    /// assert_eq!(path_str, Some("foo.txt"));
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn to_str(&self) -> Option<&str> {

src/libstd/primitive_docs.rs

@@ -411,7 +411,7 @@ mod prim_isize { }
 
 #[doc(primitive = "usize")]
 //
-/// The pointer-sized signed integer type.
+/// The pointer-sized unsigned integer type.
 ///
 /// *[See also the `std::usize` module](usize/index.html).*
 ///