Auto merge of #30750 - steveklabnik:rollup, r=steveklabnik

- Successful merges: #30683, #30698, #30699, #30700, #30716, #30720, #30727, #30729, #30735, #30749
- Failed merges:

11 files changed, 75 insertions, 29 deletions

diff --git a/README.md b/README.md
index 6e5e1ca0c32..7558065831a 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,16 @@ Read ["Installing Rust"] from [The Book].
 
 ### Building on Windows
 
+There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by
+Visual Studio, and the GNU ABI used by the GCC toolchain. Which version of Rust
+you need depends largely on what C/C++ libraries you want to interoperate with:
+for interop with software produced by Visual Studio use the MSVC build of Rust;
+for interop with GNU software built using the MinGW/MSYS2 toolchain use the GNU
+build.
+
+
+#### MinGW
+
 [MSYS2](http://msys2.github.io/) can be used to easily build Rust on Windows:
 
 1. Grab the latest MSYS2 installer and go through the installer.
@@ -63,12 +73,15 @@ Read ["Installing Rust"] from [The Book].
    ```sh
    # Update package mirrors (may be needed if you have a fresh install of MSYS2)
    $ pacman -Sy pacman-mirrors
+   ```
 
-   # Choose one based on platform: 
-   # *** see the note below ***
-   $ pacman -S mingw-w64-i686-toolchain
-   $ pacman -S mingw-w64-x86_64-toolchain
+Download [MinGW from
+here](http://mingw-w64.org/doku.php/download/mingw-builds), and choose the
+`threads=win32,exceptions=dwarf/seh` flavor when installing. After installing,
+add its `bin` directory to your `PATH`. This is due to #28260, in the future,
+installing from pacman should be just fine.
 
+   ```
    # Make git available in MSYS2 (if not already available on path)
    $ pacman -S git
 
@@ -84,16 +97,19 @@ Read ["Installing Rust"] from [The Book].
    $ ./configure
    $ make && make install
    ```
-> ***Note:*** gcc versions >= 5 currently have issues building LLVM on Windows
-> resulting in a segmentation fault when building Rust. In order to avoid this
-> it may be necessary to obtain an earlier version of gcc such as 4.9.x.  
-> Msys's `pacman` will install the latest version, so for the time being it is
-> recommended to skip gcc toolchain installation step above and use [Mingw-Builds]
-> project's installer instead.  Be sure to add gcc `bin` directory to the path
-> before running `configure`.  
-> For more information on this see issue #28260.
-
-[Mingw-Builds]: http://sourceforge.net/projects/mingw-w64/
+
+#### MSVC
+
+MSVC builds of Rust additionally require an installation of Visual Studio 2013
+(or later) so `rustc` can use its linker. Make sure to check the “C++ tools”
+option. In addition, `cmake` needs to be installed to build LLVM.
+
+With these dependencies installed, the build takes two steps:
+
+```sh
+$ ./configure
+$ make && make install
+```
 
 ## Building Documentation
 
diff --git a/src/doc/book/error-handling.md b/src/doc/book/error-handling.md
index be60ea8f81f..17eb9185266 100644
--- a/src/doc/book/error-handling.md
+++ b/src/doc/book/error-handling.md
@@ -1573,11 +1573,11 @@ fn main() {
 
     let matches = match opts.parse(&args[1..]) {
         Ok(m)  => { m }
-	Err(e) => { panic!(e.to_string()) }
+        Err(e) => { panic!(e.to_string()) }
     };
     if matches.opt_present("h") {
         print_usage(&program, opts);
-	return;
+        return;
     }
     let data_path = args[1].clone();
     let city = args[2].clone();
diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md
index 1d70ee27869..75d0093b147 100644
--- a/src/doc/book/structs.md
+++ b/src/doc/book/structs.md
@@ -88,6 +88,35 @@ fn main() {
 }
 ```
 
+Your structure can still contain `&mut` pointers, which will let
+you do some kinds of mutation:
+
+```rust
+struct Point {
+    x: i32,
+    y: i32,
+}
+
+struct PointRef<'a> {
+    x: &'a mut i32,
+    y: &'a mut i32,
+}
+
+fn main() {
+    let mut point = Point { x: 0, y: 0 };
+
+    {
+        let r = PointRef { x: &mut point.x, y: &mut point.y };
+
+        *r.x = 5;
+        *r.y = 6;
+    }
+
+    assert_eq!(5, point.x);
+    assert_eq!(6, point.y);
+}
+```
+
 # Update syntax
 
 A `struct` can include `..` to indicate that you want to use a copy of some
diff --git a/src/doc/book/the-stack-and-the-heap.md b/src/doc/book/the-stack-and-the-heap.md
index 63b73a7fc31..bc40eeb8dcc 100644
--- a/src/doc/book/the-stack-and-the-heap.md
+++ b/src/doc/book/the-stack-and-the-heap.md
@@ -539,7 +539,7 @@ instead.
 # Which to use?
 
 So if the stack is faster and easier to manage, why do we need the heap? A big
-reason is that Stack-allocation alone means you only have LIFO semantics for
+reason is that Stack-allocation alone means you only have 'Last In First Out (LIFO)' semantics for
 reclaiming storage. Heap-allocation is strictly more general, allowing storage
 to be taken from and returned to the pool in arbitrary order, but at a
 complexity cost.
diff --git a/src/doc/nomicon/vec-dealloc.md b/src/doc/nomicon/vec-dealloc.md
index b767caa4912..706fe680e00 100644
--- a/src/doc/nomicon/vec-dealloc.md
+++ b/src/doc/nomicon/vec-dealloc.md
@@ -21,7 +21,7 @@ impl<T> Drop for Vec<T> {
             let elem_size = mem::size_of::<T>();
             let num_bytes = elem_size * self.cap;
             unsafe {
-                heap::deallocate(*self.ptr, num_bytes, align);
+                heap::deallocate(*self.ptr as *mut _, num_bytes, align);
             }
         }
     }
diff --git a/src/doc/reference.md b/src/doc/reference.md
index e7cc1436824..5f71ee44379 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -208,10 +208,10 @@ A _string literal_ is a sequence of any Unicode characters enclosed within two
 which must be _escaped_ by a preceding `U+005C` character (`\`).
 
 Line-break characters are allowed in string literals. Normally they represent
-themselves (i.e. no translation), but as a special exception, when a `U+005C`
-character (`\`) occurs immediately before the newline, the `U+005C` character,
-the newline, and all whitespace at the beginning of the next line are ignored.
-Thus `a` and `b` are equal:
+themselves (i.e. no translation), but as a special exception, when an unescaped
+`U+005C` character (`\`) occurs immediately before the newline (`U+000A`), the
+`U+005C` character, the newline, and all whitespace at the beginning of the
+next line are ignored. Thus `a` and `b` are equal:
 
 ```rust
 let a = "foobar";
diff --git a/src/libcore/char.rs b/src/libcore/char.rs
index 43a1bf6e500..0fc154a0cd5 100644
--- a/src/libcore/char.rs
+++ b/src/libcore/char.rs
@@ -181,7 +181,7 @@ pub unsafe fn from_u32_unchecked(i: u32) -> char {
 ///
 /// A 'radix' here is sometimes also called a 'base'. A radix of two
 /// indicates a binary number, a radix of ten, decimal, and a radix of
-/// sixteen, hexicdecimal, to give some common values. Arbitrary
+/// sixteen, hexadecimal, to give some common values. Arbitrary
 /// radicum are supported.
 ///
 /// `from_digit()` will return `None` if the input is not a digit in
diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs
index b584e59a825..65ddae51b98 100644
--- a/src/libcore/marker.rs
+++ b/src/libcore/marker.rs
@@ -24,6 +24,8 @@ use hash::Hash;
 use hash::Hasher;
 
 /// Types that can be transferred across thread boundaries.
+///
+/// This trait is automatically derived when the compiler determines it's appropriate.
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "send"]
 #[rustc_on_unimplemented = "`{Self}` cannot be sent between threads safely"]
@@ -219,6 +221,8 @@ pub trait Copy : Clone {
 /// wrapper around the value(s) which can be mutated when behind a `&`
 /// reference; not doing this is undefined behavior (for example,
 /// `transmute`-ing from `&T` to `&mut T` is invalid).
+///
+/// This trait is automatically derived when the compiler determines it's appropriate.
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "sync"]
 #[rustc_on_unimplemented = "`{Self}` cannot be shared between threads safely"]
diff --git a/src/librustc_typeck/check/regionck.rs b/src/librustc_typeck/check/regionck.rs
index 759d561a961..801700ba673 100644
--- a/src/librustc_typeck/check/regionck.rs
+++ b/src/librustc_typeck/check/regionck.rs
@@ -61,7 +61,7 @@
 //!
 //!     struct Foo { i: i32 }
 //!     struct Bar { foo: Foo  }
-//!     fn get_i(x: &'a Bar) -> &'a i32 {
+//!     fn get_i<'a>(x: &'a Bar) -> &'a i32 {
 //!        let foo = &x.foo; // Lifetime L1
 //!        &foo.i            // Lifetime L2
 //!     }
diff --git a/src/librustc_unicode/char.rs b/src/librustc_unicode/char.rs
index 455e2feee4c..66f8068eae6 100644
--- a/src/librustc_unicode/char.rs
+++ b/src/librustc_unicode/char.rs
@@ -126,7 +126,7 @@ impl char {
     ///
     /// A 'radix' here is sometimes also called a 'base'. A radix of two
     /// indicates a binary number, a radix of ten, decimal, and a radix of
-    /// sixteen, hexicdecimal, to give some common values. Arbitrary
+    /// sixteen, hexadecimal, to give some common values. Arbitrary
     /// radicum are supported.
     ///
     /// Compared to `is_numeric()`, this function only recognizes the characters
@@ -185,7 +185,7 @@ impl char {
     ///
     /// A 'radix' here is sometimes also called a 'base'. A radix of two
     /// indicates a binary number, a radix of ten, decimal, and a radix of
-    /// sixteen, hexicdecimal, to give some common values. Arbitrary
+    /// sixteen, hexadecimal, to give some common values. Arbitrary
     /// radicum are supported.
     ///
     /// 'Digit' is defined to be only the following characters:
diff --git a/src/libsyntax/parse/token.rs b/src/libsyntax/parse/token.rs
index b942954c187..242626154fc 100644
--- a/src/libsyntax/parse/token.rs
+++ b/src/libsyntax/parse/token.rs
@@ -495,9 +495,6 @@ macro_rules! declare_special_idents_and_keywords {(
     }
 
     fn mk_fresh_ident_interner() -> IdentInterner {
-        // The indices here must correspond to the numbers in
-        // special_idents, in Keyword to_name(), and in static
-        // constants below.
         let mut init_vec = Vec::new();
         $(init_vec.push($si_str);)*
         $(init_vec.push($sk_str);)*