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

- Successful merges: #28743, #28744, #28745, #28749, #28754, #28755, #28757, #28759, #28761, #28762, #28763, #28765
- Failed merges:

src/doc/trpl/documentation.md

@@ -45,7 +45,7 @@ Rust keeps track of these comments, and uses them when generating
 documentation. This is important when documenting things like enums:
 
 ```rust
-/// The `Option` type. See [the module level documentation](../) for more.
+/// The `Option` type. See [the module level documentation](index.html) for more.
 enum Option<T> {
     /// No value
     None,
@@ -57,7 +57,7 @@ enum Option<T> {
 The above works, but this does not:
 
 ```rust,ignore
-/// The `Option` type. See [the module level documentation](../) for more.
+/// The `Option` type. See [the module level documentation](index.html) for more.
 enum Option<T> {
     None, /// No value
     Some(T), /// Some value `T`

src/doc/trpl/error-handling.md

@@ -182,7 +182,7 @@ analysis is the only way to get at the value stored inside an `Option<T>`. This
 means that you, as the programmer, must handle the case when an `Option<T>` is
 `None` instead of `Some(t)`.
 
-But wait, what about `unwrap` used in [`unwrap-double`](#code-unwrap-double)?
+But wait, what about `unwrap`,which we used [`previously`](#code-unwrap-double)?
 There was no case analysis there! Instead, the case analysis was put inside the
 `unwrap` method for you. You could define it yourself if you want:
 
@@ -211,7 +211,7 @@ that makes `unwrap` ergonomic to use. Unfortunately, that `panic!` means that
 
 ### Composing `Option<T>` values
 
-In [`option-ex-string-find`](#code-option-ex-string-find)
+In an [example from before](#code-option-ex-string-find),
 we saw how to use `find` to discover the extension in a file name. Of course,
 not all file names have a `.` in them, so it's possible that the file name has
 no extension. This *possibility of absence* is encoded into the types using

src/doc/trpl/guessing-game.md

@@ -99,9 +99,12 @@ use std::io;
 We’ll need to take user input, and then print the result as output. As such, we
 need the `io` library from the standard library. Rust only imports a few things
 by default into every program, [the ‘prelude’][prelude]. If it’s not in the
-prelude, you’ll have to `use` it directly.
+prelude, you’ll have to `use` it directly. There is also a second ‘prelude’, the
+[`io` prelude][ioprelude], which serves a similar function: you import it, and it
+imports a number of useful, `io`-related things.
 
 [prelude]: ../std/prelude/index.html
+[ioprelude]: ../std/io/prelude/index.html
 
 ```rust,ignore
 fn main() {

src/doc/trpl/primitive-types.md

@@ -162,13 +162,18 @@ A ‘slice’ is a reference to (or “view” into) another data structure. The
 useful for allowing safe, efficient access to a portion of an array without
 copying. For example, you might want to reference just one line of a file read
 into memory. By nature, a slice is not created directly, but from an existing
-variable. Slices have a length, can be mutable or not, and in many ways behave
-like arrays:
+variable binding. Slices have a defined length, can be mutable or immutable.
+
+## Slicing syntax
+
+You can use a combo of `&` and `[]` to create a slice from various things. The
+`&` indicates that slices are similar to references, and the `[]`s, with a
+range, let you define the length of the slice:
 
 ```rust
 let a = [0, 1, 2, 3, 4];
-let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3
 let complete = &a[..]; // A slice containing all of the elements in a
+let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3
 ```
 
 Slices have type `&[T]`. We’ll talk about that `T` when we cover

src/doc/trpl/testing.md

@@ -502,3 +502,5 @@ documentation tests: the `_0` is generated for the module test, and `add_two_0`
 for the function test. These will auto increment with names like `add_two_1` as
 you add more examples.
 
+We haven’t covered all of the details with writing documentation tests. For more,
+please see the [Documentation chapter](documentation.html)

src/doc/trpl/vectors.md

@@ -32,6 +32,35 @@ println!("The third element of v is {}", v[2]);
 
 The indices count from `0`, so the third element is `v[2]`.
 
+It’s also important to note that you must index with the `usize` type:
+
+```ignore
+let v = vec![1, 2, 3, 4, 5];
+
+let i: usize = 0;
+let j: i32 = 0;
+
+// works
+v[i];
+
+// doesn’t
+v[j];
+```
+
+Indexing with a non-`usize` type gives an error that looks like this:
+
+```text
+error: the trait `core::ops::Index<i32>` is not implemented for the type
+`collections::vec::Vec<_>` [E0277]
+v[j];
+^~~~
+note: the type `collections::vec::Vec<_>` cannot be indexed by `i32`
+error: aborting due to previous error
+```
+
+There’s a lot of punctuation in that message, but the core of it makes sense:
+you cannot index with an `i32`.
+
 ## Iterating
 
 Once you have a vector, you can iterate through its elements with `for`. There

src/libcollections/slice.rs

@@ -455,6 +455,8 @@ impl<T> [T] {
     /// the index `mid` itself) and the second will contain all
     /// indices from `[mid, len)` (excluding the index `len` itself).
     ///
+    /// # Panics
+    ///
     /// Panics if `mid > len`.
     ///
     /// # Examples

src/libcore/fmt/mod.rs

@@ -298,7 +298,7 @@ impl<'a> Display for Arguments<'a> {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -393,7 +393,7 @@ pub trait Debug {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -435,7 +435,7 @@ pub trait Display {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -482,7 +482,7 @@ pub trait Octal {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -530,7 +530,7 @@ pub trait Binary {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -578,7 +578,7 @@ pub trait LowerHex {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -624,7 +624,7 @@ pub trait UpperHex {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -668,7 +668,7 @@ pub trait Pointer {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///
@@ -711,7 +711,7 @@ pub trait LowerExp {
 ///
 /// For more information on formatters, see [the module-level documentation][module].
 ///
-/// [module]: ../index.html
+/// [module]: ../../std/fmt/index.html
 ///
 /// # Examples
 ///

src/libstd/io/mod.rs

@@ -370,6 +370,13 @@ fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize>
 /// throughout `std::io` take and provide types which implement the `Read`
 /// trait.
 ///
+/// Please note that each call to `read` may involve a system call, and
+/// therefore, using something that implements [`BufRead`][bufread], such as
+/// [`BufReader`][bufreader], will be more efficient.
+///
+/// [bufread]: trait.BufRead.html
+/// [bufreader]: struct.BufReader.html
+///
 /// # Examples
 ///
 /// [`File`][file]s implement `Read`: