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

Rollup of 7 pull requests

- Successful merges: #38794, #38956, #38993, #39191, #39200, #39233, #39258
- Failed merges:

7 files changed, 45 insertions, 11 deletions

diff --git a/Makefile.in b/Makefile.in
index 9e87ce1d9e6..8dbe2421390 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -17,6 +17,10 @@
 # most intimate workings of the compiler itself, you've come to the
 # right place. Let's see what's on the menu.
 #
+# Please note that most of these options only work if configure was
+# run with --disable-rustbuild. For documentation on the new build
+# system, see CONTRIBUTING.md.
+#
 # First, start with one of these build targets:
 #
 #   * all - The default. Build a complete, bootstrapped compiler.
diff --git a/src/doc/book/match.md b/src/doc/book/match.md
index d01a20083ef..52d3c6ae926 100644
--- a/src/doc/book/match.md
+++ b/src/doc/book/match.md
@@ -82,7 +82,7 @@ fn process_message(msg: Message) {
     match msg {
         Message::Quit => quit(),
         Message::ChangeColor(r, g, b) => change_color(r, g, b),
-        Message::Move { x: x, y: y } => move_cursor(x, y),
+        Message::Move { x, y: new_name_for_y } => move_cursor(x, new_name_for_y),
         Message::Write(s) => println!("{}", s),
     };
 }
diff --git a/src/doc/book/syntax-index.md b/src/doc/book/syntax-index.md
index 28403711cd7..5fa78001fad 100644
--- a/src/doc/book/syntax-index.md
+++ b/src/doc/book/syntax-index.md
@@ -45,7 +45,7 @@
 * `%` (`expr % expr`): arithmetic remainder.  Overloadable (`Rem`).
 * `%=` (`var %= expr`): arithmetic remainder & assignment. Overloadable (`RemAssign`).
 * `&` (`expr & expr`): bitwise and.  Overloadable (`BitAnd`).
-* `&` (`&expr`): borrow.  See [References and Borrowing].
+* `&` (`&expr`, `&mut expr`): borrow.  See [References and Borrowing].
 * `&` (`&type`, `&mut type`, `&'a type`, `&'a mut type`): borrowed pointer type.  See [References and Borrowing].
 * `&=` (`var &= expr`): bitwise and & assignment. Overloadable (`BitAndAssign`).
 * `&&` (`expr && expr`): logical and.
diff --git a/src/doc/book/trait-objects.md b/src/doc/book/trait-objects.md
index a0396a75fa2..00a841a75db 100644
--- a/src/doc/book/trait-objects.md
+++ b/src/doc/book/trait-objects.md
@@ -263,10 +263,7 @@ any resources of the vtable’s type: for `u8` it is trivial, but for `String` i
 will free the memory. This is necessary for owning trait objects like
 `Box<Foo>`, which need to clean-up both the `Box` allocation as well as the
 internal type when they go out of scope. The `size` and `align` fields store
-the size of the erased type, and its alignment requirements; these are
-essentially unused at the moment since the information is embedded in the
-destructor, but will be used in the future, as trait objects are progressively
-made more flexible.
+the size of the erased type, and its alignment requirements.
 
 Suppose we’ve got some values that implement `Foo`. The explicit form of
 construction and use of `Foo` trait objects might look a bit like (ignoring the
diff --git a/src/doc/grammar.md b/src/doc/grammar.md
index 690d44cc2cb..c81f2e2282b 100644
--- a/src/doc/grammar.md
+++ b/src/doc/grammar.md
@@ -510,8 +510,9 @@ unit_expr : "()" ;
 ### Structure expressions
 
 ```antlr
-struct_expr : expr_path '{' ident ':' expr
-                      [ ',' ident ':' expr ] *
+struct_expr_field_init : ident | ident ':' expr ;
+struct_expr : expr_path '{' struct_expr_field_init
+                      [ ',' struct_expr_field_init ] *
                       [ ".." expr ] '}' |
               expr_path '(' expr
                       [ ',' expr ] * ')' |
diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs
index 75205794471..a3cb1284477 100644
--- a/src/libcore/sync/atomic.rs
+++ b/src/libcore/sync/atomic.rs
@@ -21,9 +21,10 @@
 //!
 //! Each method takes an `Ordering` which represents the strength of
 //! the memory barrier for that operation. These orderings are the
-//! same as [LLVM atomic orderings][1].
+//! same as [LLVM atomic orderings][1]. For more information see the [nomicon][2].
 //!
 //! [1]: http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations
+//! [2]: https://doc.rust-lang.org/nomicon/atomics.html
 //!
 //! Atomic variables are safe to share between threads (they implement `Sync`)
 //! but they do not themselves provide the mechanism for sharing and follow the
@@ -141,6 +142,9 @@ unsafe impl<T> Sync for AtomicPtr<T> {}
 ///
 /// Rust's memory orderings are [the same as
 /// LLVM's](http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations).
+///
+/// For more information see the [nomicon][1].
+/// [1]: https://doc.rust-lang.org/nomicon/atomics.html
 #[stable(feature = "rust1", since = "1.0.0")]
 #[derive(Copy, Clone, Debug)]
 pub enum Ordering {
diff --git a/src/libstd/ascii.rs b/src/libstd/ascii.rs
index f5e9ec6d89d..b220504d2b4 100644
--- a/src/libstd/ascii.rs
+++ b/src/libstd/ascii.rs
@@ -66,6 +66,11 @@ pub trait AsciiExt {
     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
     /// but non-ASCII letters are unchanged.
     ///
+    /// To uppercase the string in-place, use [`make_ascii_uppercase`].
+    ///
+    /// To uppercase ASCII characters in addition to non-ASCII characters, use
+    /// [`str::to_uppercase`].
+    ///
     /// # Examples
     ///
     /// ```
@@ -77,6 +82,9 @@ pub trait AsciiExt {
     /// assert_eq!('A', ascii.to_ascii_uppercase());
     /// assert_eq!('❤', utf8.to_ascii_uppercase());
     /// ```
+    ///
+    /// [`make_ascii_uppercase`]: #tymethod.make_ascii_uppercase
+    /// [`str::to_uppercase`]: ../primitive.str.html#method.to_uppercase
     #[stable(feature = "rust1", since = "1.0.0")]
     fn to_ascii_uppercase(&self) -> Self::Owned;
 
@@ -85,6 +93,11 @@ pub trait AsciiExt {
     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
     /// but non-ASCII letters are unchanged.
     ///
+    /// To lowercase the string in-place, use [`make_ascii_lowercase`].
+    ///
+    /// To lowercase ASCII characters in addition to non-ASCII characters, use
+    /// [`str::to_lowercase`].
+    ///
     /// # Examples
     ///
     /// ```
@@ -96,6 +109,9 @@ pub trait AsciiExt {
     /// assert_eq!('a', ascii.to_ascii_lowercase());
     /// assert_eq!('❤', utf8.to_ascii_lowercase());
     /// ```
+    ///
+    /// [`make_ascii_lowercase`]: #tymethod.make_ascii_lowercase
+    /// [`str::to_lowercase`]: ../primitive.str.html#method.to_lowercase
     #[stable(feature = "rust1", since = "1.0.0")]
     fn to_ascii_lowercase(&self) -> Self::Owned;
 
@@ -123,7 +139,11 @@ pub trait AsciiExt {
 
     /// Converts this type to its ASCII upper case equivalent in-place.
     ///
-    /// See `to_ascii_uppercase` for more information.
+    /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
+    /// but non-ASCII letters are unchanged.
+    ///
+    /// To return a new uppercased string without modifying the existing one, use
+    /// [`to_ascii_uppercase`].
     ///
     /// # Examples
     ///
@@ -136,12 +156,18 @@ pub trait AsciiExt {
     ///
     /// assert_eq!('A', ascii);
     /// ```
+    ///
+    /// [`to_ascii_uppercase`]: #tymethod.to_ascii_uppercase
     #[stable(feature = "ascii", since = "1.9.0")]
     fn make_ascii_uppercase(&mut self);
 
     /// Converts this type to its ASCII lower case equivalent in-place.
     ///
-    /// See `to_ascii_lowercase` for more information.
+    /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
+    /// but non-ASCII letters are unchanged.
+    ///
+    /// To return a new lowercased string without modifying the existing one, use
+    /// [`to_ascii_lowercase`].
     ///
     /// # Examples
     ///
@@ -154,6 +180,8 @@ pub trait AsciiExt {
     ///
     /// assert_eq!('a', ascii);
     /// ```
+    ///
+    /// [`to_ascii_lowercase`]: #tymethod.to_ascii_lowercase
     #[stable(feature = "ascii", since = "1.9.0")]
     fn make_ascii_lowercase(&mut self);
 }