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

- Successful merges: #25788, #25861, #25864, #25865, #25866, #25873, #25876, #25883, #25886
- Failed merges:

Author: bors

src/doc/style/features/functions-and-methods/README.md

@@ -20,6 +20,7 @@ for any operation that is clearly associated with a particular
 type.
 
 Methods have numerous advantages over functions:
+
 * They do not need to be imported or qualified to be used: all you
   need is a value of the appropriate type.
 * Their invocation performs autoborrowing (including mutable borrows).

src/doc/style/features/functions-and-methods/input.md

@@ -159,7 +159,7 @@ fn foo(a: u8) { ... }
 Note that
 [`ascii::Ascii`](http://static.rust-lang.org/doc/master/std/ascii/struct.Ascii.html)
 is a _wrapper_ around `u8` that guarantees the highest bit is zero; see
-[newtype patterns]() for more details on creating typesafe wrappers.
+[newtype patterns](../types/newtype.md) for more details on creating typesafe wrappers.
 
 Static enforcement usually comes at little run-time cost: it pushes the
 costs to the boundaries (e.g. when a `u8` is first converted into an

src/doc/style/features/let.md

@@ -34,7 +34,7 @@ Prefer
 
 ```rust
 let foo = match bar {
-    Baz  => 0,
+    Baz => 0,
     Quux => 1
 };
 ```
@@ -44,7 +44,7 @@ over
 ```rust
 let foo;
 match bar {
-    Baz  => {
+    Baz => {
         foo = 0;
     }
     Quux => {
@@ -61,8 +61,8 @@ conditional expression.
 Prefer
 
 ```rust
-s.iter().map(|x| x * 2)
-        .collect::<Vec<_>>()
+let v = s.iter().map(|x| x * 2)
+                .collect::<Vec<_>>();
 ```
 
 over

src/doc/style/ownership/builders.md

@@ -16,7 +16,7 @@ If `T` is such a data structure, consider introducing a `T` _builder_:
    value. When possible, choose a better name: e.g. `Command` is the builder for
    `Process`.
 2. The builder constructor should take as parameters only the data _required_ to
-   to make a `T`.
+   make a `T`.
 3. The builder should offer a suite of convenient methods for configuration,
    including setting up compound inputs (like slices) incrementally.
    These methods should return `self` to allow chaining.

src/doc/trpl/README.md

@@ -15,7 +15,7 @@ language would.
 
 [rust]: http://rust-lang.org
 
-“The Rust Programming Language” is split into seven sections. This introduction
+“The Rust Programming Language” is split into eight sections. This introduction
 is the first. After this:
 
 * [Getting started][gs] - Set up your computer for Rust development.

src/doc/trpl/glossary.md

@@ -19,7 +19,7 @@ In the example above `x` and `y` have arity 2. `z` has arity 3.
 
 When a compiler is compiling your program, it does a number of different
 things. One of the things that it does is turn the text of your program into an
-‘abstract syntax tree’, or‘AST’. This tree is a representation of the
+‘abstract syntax tree’, or ‘AST’. This tree is a representation of the
 structure of your program. For example, `2 + 3` can be turned into a tree:
 
 ```text

src/doc/trpl/lifetimes.md

@@ -134,8 +134,29 @@ x: &'a i32,
 # }
 ```
 
-uses it. So why do we need a lifetime here? We need to ensure that any
-reference to the contained `i32` does not outlive the containing `Foo`.
+uses it. So why do we need a lifetime here? We need to ensure that any reference
+to a `Foo` cannot outlive the reference to an `i32` it contains.
+
+If you have multiple references, you can use the same lifetime multiple times:
+
+```rust
+fn x_or_y<'a>(x: &'a str, y: &'a str) -> &'a str {
+#    x
+# }
+```
+
+This says that `x` and `y` both are alive for the same scope, and that the
+return value is also alive for that scope. If you wanted `x` and `y` to have
+different lifetimes, you can use multiple lifetime parameters:
+
+```rust
+fn x_or_y<'a, 'b>(x: &'a str, y: &'b str) -> &'a str {
+#    x
+# }
+```
+
+In this example, `x` and `y` have different valid scopes, but the return value
+has the same lifetime as `x`.
 
 ## Thinking in scopes
 

src/doc/trpl/method-syntax.md

@@ -4,7 +4,7 @@ Functions are great, but if you want to call a bunch of them on some data, it
 can be awkward. Consider this code:
 
 ```rust,ignore
-baz(bar(foo)));
+baz(bar(foo));
 ```
 
 We would read this left-to right, and so we see ‘baz bar foo’. But this isn’t the

src/doc/trpl/traits.md

@@ -285,7 +285,7 @@ fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug {
 
 fn main() {
     foo("Hello", "world");
-    bar("Hello", "workd");
+    bar("Hello", "world");
 }
 ```
 

src/libcore/mem.rs

@@ -52,20 +52,61 @@ pub use intrinsics::transmute;
 /// * `mpsc::{Sender, Receiver}` cycles (they use `Arc` internally)
 /// * Panicking destructors are likely to leak local resources
 ///
+/// # When To Use
+///
+/// There's only a few reasons to use this function. They mainly come
+/// up in unsafe code or FFI code.
+///
+/// * You have an uninitialized value, perhaps for performance reasons, and
+///   need to prevent the destructor from running on it.
+/// * You have two copies of a value (like `std::mem::swap`), but need the
+///   destructor to only run once to prevent a double free.
+/// * Transferring resources across FFI boundries.
+///
 /// # Example
 ///
-/// ```rust,no_run
+/// Leak some heap memory by never deallocating it.
+///
+/// ```rust
 /// use std::mem;
-/// use std::fs::File;
 ///
-/// // Leak some heap memory by never deallocating it
 /// let heap_memory = Box::new(3);
 /// mem::forget(heap_memory);
+/// ```
+///
+/// Leak an I/O object, never closing the file.
+///
+/// ```rust,no_run
+/// use std::mem;
+/// use std::fs::File;
 ///
-/// // Leak an I/O object, never closing the file
 /// let file = File::open("foo.txt").unwrap();
 /// mem::forget(file);
 /// ```
+///
+/// The swap function uses forget to good effect.
+///
+/// ```rust
+/// use std::mem;
+/// use std::ptr;
+///
+/// fn swap<T>(x: &mut T, y: &mut T) {
+///     unsafe {
+///         // Give ourselves some scratch space to work with
+///         let mut t: T = mem::uninitialized();
+///
+///         // Perform the swap, `&mut` pointers never alias
+///         ptr::copy_nonoverlapping(&*x, &mut t, 1);
+///         ptr::copy_nonoverlapping(&*y, x, 1);
+///         ptr::copy_nonoverlapping(&t, y, 1);
+///
+///         // y and t now point to the same thing, but we need to completely
+///         // forget `t` because we do not want to run the destructor for `T`
+///         // on its value, which is still owned somewhere outside this function.
+///         mem::forget(t);
+///     }
+/// }
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub fn forget<T>(t: T) {
     unsafe { intrinsics::forget(t) }
@@ -267,8 +308,9 @@ pub fn swap<T>(x: &mut T, y: &mut T) {
         ptr::copy_nonoverlapping(&*y, x, 1);
         ptr::copy_nonoverlapping(&t, y, 1);
 
-        // y and t now point to the same thing, but we need to completely forget `t`
-        // because it's no longer relevant.
+        // y and t now point to the same thing, but we need to completely
+        // forget `t` because we do not want to run the destructor for `T`
+        // on its value, which is still owned somewhere outside this function.
         forget(t);
     }
 }