Rollup of 13 pull requests

src/doc/book/syntax-index.md

@@ -94,7 +94,7 @@
 * `|` (`|…| expr`): closures.  See [Closures].
 * `|=` (`var |= expr`): bitwise or & assignment. Overloadable (`BitOrAssign`).
 * `||` (`expr || expr`): logical or.
-* `_`: "ignored" pattern binding.  See [Patterns (Ignoring bindings)].
+* `_`: "ignored" pattern binding (see [Patterns (Ignoring bindings)]). Also used to make integer-literals readable (see [Reference (Integer literals)]).
 
 ## Other Syntax
 
@@ -231,6 +231,7 @@
 [Primitive Types (Tuples)]: primitive-types.html#tuples
 [Raw Pointers]: raw-pointers.html
 [Reference (Byte String Literals)]: ../reference.html#byte-string-literals
+[Reference (Integer literals)]: ../reference.html#integer-literals
 [Reference (Raw Byte String Literals)]: ../reference.html#raw-byte-string-literals
 [Reference (Raw String Literals)]: ../reference.html#raw-string-literals
 [References and Borrowing]: references-and-borrowing.html

src/doc/nomicon/phantom-data.md

@@ -50,7 +50,7 @@ struct Vec<T> {
 }
 ```
 
-Unlike the previous example it *appears* that everything is exactly as we
+Unlike the previous example, it *appears* that everything is exactly as we
 want. Every generic argument to Vec shows up in at least one field.
 Good to go!
 
@@ -84,4 +84,3 @@ standard library made a utility for itself called `Unique<T>` which:
 * includes a `PhantomData<T>`
 * auto-derives Send/Sync as if T was contained
 * marks the pointer as NonZero for the null-pointer optimization
-

src/doc/reference.md

@@ -1653,14 +1653,43 @@ the Rust ABI and the foreign ABI.
 A number of [attributes](#ffi-attributes) control the behavior of external blocks.
 
 By default external blocks assume that the library they are calling uses the
-standard C "cdecl" ABI. Other ABIs may be specified using an `abi` string, as
-shown here:
+standard C ABI on the specific platform. Other ABIs may be specified using an
+`abi` string, as shown here:
 
 ```ignore
 // Interface to the Windows API
 extern "stdcall" { }
 ```
 
+There are three ABI strings which are cross-platform, and which all compilers
+are guaranteed to support:
+
+* `extern "Rust"` -- The default ABI when you write a normal `fn foo()` in any
+  Rust code.
+* `extern "C"` -- This is the same as `extern fn foo()`; whatever the default
+  your C compiler supports.
+* `extern "system"` -- Usually the same as `extern "C"`, except on Win32, in
+  which case it's `"stdcall"`, or what you should use to link to the Windows API
+  itself
+
+There are also some platform-specific ABI strings:
+
+* `extern "cdecl"` -- The default for x86\_32 C code.
+* `extern "stdcall"` -- The default for the Win32 API on x86\_32.
+* `extern "win64"` -- The default for C code on x86\_64 Windows.
+* `extern "aapcs"` -- The default for ARM.
+* `extern "fastcall"` -- The `fastcall` ABI -- corresponds to MSVC's
+  `__fastcall` and GCC and clang's `__attribute__((fastcall))`
+* `extern "vectorcall"` -- The `vectorcall` ABI -- corresponds to MSVC's
+  `__vectorcall` and clang's `__attribute__((vectorcall))`
+
+Finally, there are some rustc-specific ABI strings:
+
+* `extern "rust-intrinsic"` -- The ABI of rustc intrinsics.
+* `extern "rust-call"` -- The ABI of the Fn::call trait functions.
+* `extern "platform-intrinsic"` -- Specific platform intrinsics -- like, for
+  example, `sqrt` -- have this ABI. You should never have to deal with it.
+
 The `link` attribute allows the name of the library to be specified. When
 specified the compiler will attempt to link against the native library of the
 specified name.

src/doc/rustc-ux-guidelines.md

@@ -56,6 +56,10 @@ Error explanations are long form descriptions of error messages provided with
 the compiler. They are accessible via the `--explain` flag. Each explanation
 comes with an example of how to trigger it and advice on how to fix it.
 
+Long error codes explanations are a very important part of Rust. Having an
+explanation of what failed helps to understand the error and is appreciated by
+Rust developers of all skill levels.
+
 * All of them are accessible [online](http://doc.rust-lang.org/error-index.html),
   which are auto-generated from rustc source code in different places:
   [librustc](https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs),
@@ -74,6 +78,124 @@ code with backticks.
 * When talking about the compiler, call it `the compiler`, not `Rust` or
 `rustc`.
 
+Note: The following sections are mostly a repaste of [RFC 1567](https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md).
+
+### Template
+
+Long error descriptions should match the following template. The next few
+sections of this document describe what each section is about.
+
+```rust
+E000: r##"
+[Error description]
+
+Example of erroneous code:
+
+\```compile_fail
+[Minimal example]
+\```
+
+[Error explanation]
+
+\```
+[How to fix the problem]
+\```
+
+[Optional Additional information]
+```
+
+### Error description
+
+Provide a more detailed error message. For example:
+
+```rust
+extern crate a;
+extern crate b as a;
+```
+
+We get the `E0259` error code which says "an extern crate named `a` has already been imported in this module" and the error explanation says: "The name chosen for an external crate conflicts with another external crate that has been imported into the current module.".
+
+### Minimal example
+
+Provide an erroneous code example which directly follows `Error description`. The erroneous example will be helpful for the `How to fix the problem`. Making it as simple as possible is really important in order to help readers to understand what the error is about. A comment should be added with the error on the same line where the errors occur. Example:
+
+```rust
+type X = u32<i32>; // error: type parameters are not allowed on this type
+```
+
+If the error comments is too long to fit 80 columns, split it up like this, so the next line start at the same column of the previous line:
+
+```rust
+type X = u32<'static>; // error: lifetime parameters are not allowed on
+                       //        this type
+```
+
+And if the sample code is too long to write an effective comment, place your comment on the line before the sample code:
+
+```rust
+// error: lifetime parameters are not allowed on this type
+fn super_long_function_name_and_thats_problematic() {}
+```
+
+Of course, it the comment is too long, the split rules still applies.
+
+### Error explanation
+
+Provide a full explanation about "__why__ you get the error" and some leads on __how__ to fix it. If needed, use additional code snippets to improve your explanations.
+
+### How to fix the problem
+
+This part will show how to fix the error that we saw previously in the `Minimal example`, with comments explaining how it was fixed.
+
+### Additional information
+
+Some details which might be useful for the users, let's take back `E0109` example. At the end, the supplementary explanation is the following: "Note that type parameters for enum-variant constructors go after the variant, not after the enum (`Option::None::<u32>`, not `Option::<u32>::None`).". It provides more information, not directly linked to the error, but it might help user to avoid doing another error.
+
+### Full Example
+
+Now let's take a full example:
+
+> E0409: r##"
+> An "or" pattern was used where the variable bindings are not consistently bound
+> across patterns.
+>
+> Example of erroneous code:
+>
+> ```compile_fail
+> let x = (0, 2);
+> match x {
+>     (0, ref y) | (y, 0) => { /* use y */} // error: variable `y` is bound with
+>                                           //        different mode in pattern #2
+>                                           //        than in pattern #1
+>     _ => ()
+> }
+> ```
+>
+> Here, `y` is bound by-value in one case and by-reference in the other.
+>
+> To fix this error, just use the same mode in both cases.
+> Generally using `ref` or `ref mut` where not already used will fix this:
+>
+> ```ignore
+> let x = (0, 2);
+> match x {
+>     (0, ref y) | (ref y, 0) => { /* use y */}
+>     _ => ()
+> }
+> ```
+>
+> Alternatively, split the pattern:
+>
+> ```
+> let x = (0, 2);
+> match x {
+>     (y, 0) => { /* use y */ }
+>     (0, ref y) => { /* use y */}
+>     _ => ()
+> }
+> ```
+> "##,
+
 ## Compiler Flags
 
 * Flags should be orthogonal to each other. For example, if we'd have a

src/libcollections/vec_deque.rs

@@ -402,6 +402,8 @@ impl<T> VecDeque<T> {
 
     /// Retrieves an element in the `VecDeque` by index.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -425,6 +427,8 @@ impl<T> VecDeque<T> {
 
     /// Retrieves an element in the `VecDeque` mutably by index.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -456,6 +460,8 @@ impl<T> VecDeque<T> {
     ///
     /// Fails if there is no element with either index.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1180,6 +1186,8 @@ impl<T> VecDeque<T> {
     ///
     /// Returns `None` if `index` is out of bounds.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1214,6 +1222,8 @@ impl<T> VecDeque<T> {
     ///
     /// Returns `None` if `index` is out of bounds.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1245,6 +1255,8 @@ impl<T> VecDeque<T> {
     /// end is closer to the insertion point will be moved to make room,
     /// and all the affected elements will be moved to new positions.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Panics
     ///
     /// Panics if `index` is greater than `VecDeque`'s length
@@ -1472,6 +1484,8 @@ impl<T> VecDeque<T> {
     /// room, and all the affected elements will be moved to new positions.
     /// Returns `None` if `index` is out of bounds.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1651,6 +1665,8 @@ impl<T> VecDeque<T> {
     ///
     /// Note that the capacity of `self` does not change.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Panics
     ///
     /// Panics if `at > len`