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

- Successful merges: #23782, #24455, #24490, #24493, #24494, #24496, #24498, #24499, #24501, #24502, #24506, #24507, #24508, #24509, #24510
- Failed merges: #24488

src/doc/complement-design-faq.md

@@ -56,7 +56,7 @@ Types which are [`Sync`][sync] are thread-safe when multiple shared
 references to them are used concurrently. Types which are not `Sync` are not
 thread-safe, and thus when used in a global require unsafe code to use.
 
-[sync]: core/kinds/trait.Sync.html
+[sync]: core/marker/trait.Sync.html
 
 ### If mutable static items that implement `Sync` are safe, why is taking &mut SHARABLE unsafe?
 
@@ -139,7 +139,7 @@ and explicitly calling the `clone` method. Making user-defined copy operators
 explicit surfaces the underlying complexity, forcing the developer to opt-in
 to potentially expensive operations.
 
-[copy]: core/kinds/trait.Copy.html
+[copy]: core/marker/trait.Copy.html
 [clone]: core/clone/trait.Clone.html
 
 ## No move constructors

src/doc/reference.md

@@ -2177,6 +2177,14 @@ The following configurations must be defined by the implementation:
 * `unix`. See `target_family`.
 * `windows`. See `target_family`.
 
+You can also set another attribute based on a `cfg` variable with `cfg_attr`:
+
+```rust,ignore
+#[cfg_attr(a, b)]
+```
+
+Will be the same as `#[b]` if `a` is set by `cfg`, and nothing otherwise.
+
 ### Lint check attributes
 
 A lint check names a potentially undesirable coding pattern, such as
@@ -2368,7 +2376,7 @@ The currently implemented features of the reference compiler are:
                     removed entirely for something more wholesome.
 
 * `custom_attribute` - Allows the usage of attributes unknown to the compiler
-                       so that new attributes can be added in a bacwards compatible
+                       so that new attributes can be added in a backwards compatible
                        manner (RFC 572).
 
 * `custom_derive` - Allows the use of `#[derive(Foo,Bar)]` as sugar for
@@ -2397,7 +2405,7 @@ The currently implemented features of the reference compiler are:
                  nasty hack that will certainly be removed.
 
 * `main` - Allows use of the `#[main]` attribute, which changes the entry point
-           into a Rust program. This capabiilty is subject to change.
+           into a Rust program. This capability is subject to change.
 
 * `macro_reexport` - Allows macros to be re-exported from one crate after being imported
                      from another. This feature was originally designed with the sole
@@ -2444,7 +2452,9 @@ The currently implemented features of the reference compiler are:
 * `simd_ffi` - Allows use of SIMD vectors in signatures for foreign functions.
                The SIMD interface is subject to change.
 
-* `staged_api` - Allows usage of stability markers and `#![staged_api]` in a crate
+* `staged_api` - Allows usage of stability markers and `#![staged_api]` in a
+                 crate. Stability markers are also attributes: `#[stable]`,
+                 `#[unstable]`, and `#[deprecated]` are the three levels.
 
 * `static_assert` - The `#[static_assert]` functionality is experimental and
                     unstable. The attribute can be attached to a `static` of
@@ -2453,7 +2463,7 @@ The currently implemented features of the reference compiler are:
                     is unintuitive and suboptimal.
 
 * `start` - Allows use of the `#[start]` attribute, which changes the entry point
-            into a Rust program. This capabiilty, especially the signature for the
+            into a Rust program. This capability, especially the signature for the
             annotated function, is subject to change.
 
 * `struct_inherit` - Allows using struct inheritance, which is barely

src/doc/trpl/closures.md

@@ -205,11 +205,11 @@ you tons of control over what your code does, and closures are no different.
 
 Rust's implementation of closures is a bit different than other languages. They
 are effectively syntax sugar for traits. You'll want to make sure to have read
-the [traits chapter][traits] before this one, as well as the chapter on [static
-and dynamic dispatch][dispatch], which talks about trait objects.
+the [traits chapter][traits] before this one, as well as the chapter on [trait
+objects][trait-objects].
 
 [traits]: traits.html
-[dispatch]: static-and-dynamic-dispatch.html
+[trait-objects]: trait-objects.html
 
 Got all that? Good.
 

src/doc/trpl/concurrency.md

@@ -176,8 +176,8 @@ Here's the error:
                   ^~~~~~~~~~~~~
 ```
 
-You see, [`Mutex`](std/sync/struct.Mutex.html) has a
-[`lock`](http://doc.rust-lang.org/nightly/std/sync/struct.Mutex.html#method.lock)
+You see, [`Mutex`](../std/sync/struct.Mutex.html) has a
+[`lock`](../std/sync/struct.Mutex.html#method.lock)
 method which has this signature:
 
 ```ignore

src/doc/trpl/documentation.md

@@ -380,7 +380,10 @@ $ rustdoc --test path/to/my/crate/root.rs
 $ cargo test
 ```
 
-That's right, `cargo test` tests embedded documentation too.
+That's right, `cargo test` tests embedded documentation too. However, 
+`cargo test` will not test binary crates, only library ones. This is
+due to the way `rustdoc` works: it links against the library to be tested,
+but with a binary, there’s nothing to link to.
 
 There are a few more annotations that are useful to help `rustdoc` do the right
 thing when testing your code:
@@ -560,3 +563,13 @@ This sets a few different options, with a logo, favicon, and a root URL.
 - `--html-before-content FILE`: includes the contents of FILE directly after
   `<body>`, before the rendered content (including the search bar).
 - `--html-after-content FILE`: includes the contents of FILE after all the rendered content.
+
+## Security note
+
+The Markdown in documentation comments is placed without processing into
+the final webpage. Be careful with literal HTML:
+
+```rust
+/// <script>alert(document.cookie)</script>
+# fn foo() {}
+```

src/doc/trpl/error-handling.md

@@ -20,18 +20,18 @@ panic. A *failure* is an error that can be recovered from in some way. A
 *panic* is an error that cannot be recovered from.
 
 What do we mean by "recover"? Well, in most cases, the possibility of an error
-is expected. For example, consider the `from_str` function:
+is expected. For example, consider the `parse` function:
 
-```{rust,ignore}
-from_str("5");
+```ignore
+"5".parse();
 ```
 
-This function takes a string argument and converts it into another type. But
-because it's a string, you can't be sure that the conversion actually works.
-For example, what should this convert to?
+This method converts a string into another type. But because it's a string, you
+can't be sure that the conversion actually works. For example, what should this
+convert to?
 
-```{rust,ignore}
-from_str("hello5world");
+```ignore
+"hello5world".parse();
 ```
 
 This won't work. So we know that this function will only work properly for some
@@ -40,7 +40,8 @@ inputs. It's expected behavior. We call this kind of error a *failure*.
 On the other hand, sometimes, there are errors that are unexpected, or which
 we cannot recover from. A classic example is an `assert!`:
 
-```{rust,ignore}
+```rust
+# let x = 5;
 assert!(x == 5);
 ```
 
@@ -119,17 +120,19 @@ Rust calls these sorts of errors *panics*.
 # Handling errors with `Option` and `Result`
 
 The simplest way to indicate that a function may fail is to use the `Option<T>`
-type. Remember our `from_str()` example? Here's its type signature:
+type. For example, the `find` method on strings attempts to find a pattern
+in a string, and returns an `Option`:
 
-```{rust,ignore}
-pub fn from_str<A: FromStr>(s: &str) -> Option<A>
+```rust
+let s = "foo";
+
+assert_eq!(s.find('f'), Some(0));
+assert_eq!(s.find('z'), None);
 ```
 
-`from_str()` returns an `Option<A>`. If the conversion succeeds, it will return
-`Some(value)`, and if it fails, it will return `None`.
 
 This is appropriate for the simplest of cases, but doesn't give us a lot of
-information in the failure case. What if we wanted to know _why_ the conversion
+information in the failure case. What if we wanted to know _why_ the function
 failed? For this, we can use the `Result<T, E>` type. It looks like this:
 
 ```rust
@@ -297,5 +300,5 @@ It's worth noting that you can only use `try!` from a function that returns a
 `Result`, which means that you cannot use `try!` inside of `main()`, because
 `main()` doesn't return anything.
 
-`try!` makes use of [`From<Error>`](../std/convert/trait.From.hml) to determine
+`try!` makes use of [`From<Error>`](../std/convert/trait.From.html) to determine
 what to return in the error case.

src/doc/trpl/installing-rust.md

@@ -91,9 +91,9 @@ If not, there are a number of places where you can get help. The easiest is
 [Mibbit][mibbit]. Click that link, and you'll be chatting with other Rustaceans
 (a silly nickname we call ourselves), and we can help you out. Other great
 resources include [the user’s forum][users], and
-[Stack Overflow][stack overflow].
+[Stack Overflow][stackoverflow].
 
 [irc]: irc://irc.mozilla.org/#rust
 [mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
 [users]: http://users.rust-lang.org/ 
-[stack overflow]: http://stackoverflow.com/questions/tagged/rust
+[stackoverflow]: http://stackoverflow.com/questions/tagged/rust

src/doc/trpl/macros.md

@@ -33,7 +33,7 @@ mind.
 You may have seen the `vec!` macro, used to initialize a [vector][] with any
 number of elements.
 
-[vector]: arrays-vectors-and-slices.html
+[vector]: vectors.html
 
 ```rust
 let x: Vec<u32> = vec![1, 2, 3];

src/doc/trpl/primitive-types.md

@@ -216,6 +216,18 @@ In systems programming languages, strings are a bit more complex than in other
 languages. For now, just read `&str` as a *string slice*, and we’ll learn more
 soon.
 
+You can assign one tuple into another, if they have the same contained types
+and [arity]. Tuples have the same arity when they have the same length.
+
+[arity]: glossary.html#arity
+
+```rust
+let mut x = (1, 2); // x: (i32, i32)
+let y = (2, 3); // y: (i32, i32)
+
+x = y;
+```
+
 You can access the fields in a tuple through a *destructuring let*. Here’s
 an example:
 
@@ -235,20 +247,24 @@ or "breaks up," the tuple, and assigns the bits to three bindings.
 
 This pattern is very powerful, and we’ll see it repeated more later.
 
-There are also a few things you can do with a tuple as a whole, without
-destructuring. You can assign one tuple into another, if they have the same
-contained types and [arity]. Tuples have the same arity when they have the same
-length.
+## Tuple Indexing
+
+You can also access fields of a tuple with indexing syntax:
 
-[arity]: glossary.html#arity
 
 ```rust
-let mut x = (1, 2); // x: (i32, i32)
-let y = (2, 3); // y: (i32, i32)
+let tuple = (1, 2, 3);
 
-x = y;
+let x = tuple.0;
+let y = tuple.1;
+let z = tuple.2;
+
+println!("x is {}", x);
 ```
 
+Like array indexing, it starts at zero, but unlike array indexing, it uses a
+`.`, rather than `[]`s.
+
 You can find more documentation for tuples [in the standard library
 documentation][tuple].
 

src/libcore/iter.rs

@@ -179,8 +179,8 @@ pub trait Iterator {
 
     /// Creates an iterator that iterates over both this and the specified
     /// iterators simultaneously, yielding the two elements as pairs. When
-    /// either iterator returns None, all further invocations of next() will
-    /// return None.
+    /// either iterator returns `None`, all further invocations of next() will
+    /// return `None`.
     ///
     /// # Examples
     ///
@@ -254,7 +254,7 @@ pub trait Iterator {
     }
 
     /// Creates an iterator that both filters and maps elements.
-    /// If the specified function returns None, the element is skipped.
+    /// If the specified function returns `None`, the element is skipped.
     /// Otherwise the option is unwrapped and the new value is yielded.
     ///
     /// # Examples
@@ -403,7 +403,7 @@ pub trait Iterator {
     /// Creates a new iterator that behaves in a similar fashion to fold.
     /// There is a state which is passed between each iteration and can be
     /// mutated as necessary. The yielded values from the closure are yielded
-    /// from the Scan instance when not None.
+    /// from the Scan instance when not `None`.
     ///
     /// # Examples
     ///
@@ -701,7 +701,7 @@ pub trait Iterator {
 
     /// Returns the index of the last element satisfying the specified predicate
     ///
-    /// If no element matches, None is returned.
+    /// If no element matches, `None` is returned.
     ///
     /// Does not consume the iterator *before* the first found element.
     ///

src/libcore/raw.rs

@@ -71,11 +71,11 @@ impl<T> Clone for Slice<T> {
 /// The representation of a trait object like `&SomeTrait`.
 ///
 /// This struct has the same layout as types like `&SomeTrait` and
-/// `Box<AnotherTrait>`. The [Static and Dynamic Dispatch chapter of the
+/// `Box<AnotherTrait>`. The [Trait Objects chapter of the
 /// Book][moreinfo] contains more details about the precise nature of
 /// these internals.
 ///
-/// [moreinfo]: ../../book/static-and-dynamic-dispatch.html#representation
+/// [moreinfo]: ../../book/trait-objects.html#representation
 ///
 /// `TraitObject` is guaranteed to match layouts, but it is not the
 /// type of trait objects (e.g. the fields are not directly accessible

src/libcore/result.rs

@@ -86,12 +86,12 @@
 //! useful value.
 //!
 //! Consider the `write_all` method defined for I/O types
-//! by the [`Write`](../io/trait.Write.html) trait:
+//! by the [`Write`](../../std/io/trait.Write.html) trait:
 //!
 //! ```
 //! use std::io;
 //!
-//! trait Writer {
+//! trait Write {
 //!     fn write_all(&mut self, bytes: &[u8]) -> Result<(), io::Error>;
 //! }
 //! ```