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

- Successful merges: #31473, #31513, #31514, #31515, #31516, #31520
- Failed merges:

6 files changed, 78 insertions, 34 deletions

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index 2087148d844..d42b9489180 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -521,7 +521,7 @@ impl OpenOptions {
     /// No file is allowed to exist at the target location, also no (dangling)
     /// symlink.
     ///
-    /// This option is usefull because it as atomic. Otherwise between checking
+    /// This option is useful because it as atomic. Otherwise between checking
     /// whether a file exists and creating a new one, the file may have been
     /// created by another process (a TOCTOU race condition / attack).
     ///
diff --git a/src/libstd/memchr.rs b/src/libstd/memchr.rs
index 27702e2e59a..1d97611eabb 100644
--- a/src/libstd/memchr.rs
+++ b/src/libstd/memchr.rs
@@ -150,7 +150,7 @@ mod fallback {
         // Scan for a single byte value by reading two `usize` words at a time.
         //
         // Split `text` in three parts
-        // - unaligned inital part, before the first word aligned address in text
+        // - unaligned initial part, before the first word aligned address in text
         // - body, scan by 2 words at a time
         // - the last remaining part, < 2 word size
         let len = text.len();
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index faaff494cab..dd0d874ee4b 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -8,10 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Numeric traits and functions for generic mathematics
+//! Additional functionality for numerics.
 //!
-//! These are implemented for the primitive numeric types in `std::{u8, u16,
-//! u32, u64, usize, i8, i16, i32, i64, isize, f32, f64}`.
+//! This module provides some extra types that are useful when doing numerical
+//! work. See the individual documentation for each piece for more information.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 #![allow(missing_docs)]
diff --git a/src/libstd/panic.rs b/src/libstd/panic.rs
index 3677bd27b16..83df54f1830 100644
--- a/src/libstd/panic.rs
+++ b/src/libstd/panic.rs
@@ -84,7 +84,7 @@ pub use panicking::{take_handler, set_handler, PanicInfo, Location};
 /// recover safe. The general idea is that any mutable state which can be shared
 /// across `recover` is not recover safe by default. This is because it is very
 /// easy to witness a broken invariant outside of `recover` as the data is
-/// simply accesed as usual.
+/// simply accessed as usual.
 ///
 /// Types like `&Mutex<T>`, however, are recover safe because they implement
 /// poisoning by default. They still allow witnessing a broken invariant, but
diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs
index e04a676b812..a0db471dece 100644
--- a/src/libstd/prelude/mod.rs
+++ b/src/libstd/prelude/mod.rs
@@ -17,7 +17,7 @@
 //!
 //! The *prelude* is the list of things that Rust automatically imports into
 //! every Rust program. It's kept as small as possible, and is focused on
-//! things, particuarly traits, which are used in almost every single Rust
+//! things, particularly traits, which are used in almost every single Rust
 //! program.
 //!
 //! On a technical level, Rust inserts
diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index ed59c51b0f0..ad93fe0094a 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -357,50 +357,94 @@ mod prim_str { }
 //
 /// A finite heterogeneous sequence, `(T, U, ..)`.
 ///
-/// To access the _N_-th element of a tuple one can use `N` itself
-/// as a field of the tuple.
+/// Let's cover each of those in turn:
 ///
-/// Indexing starts from zero, so `0` returns first value, `1`
-/// returns second value, and so on. In general, a tuple with _S_
-/// elements provides aforementioned fields from `0` to `S-1`.
+/// Tuples are *finite*. In other words, a tuple has a length. Here's a tuple
+/// of length `3`:
+///
+/// ```
+/// ("hello", 5, 'c');
+/// ```
+///
+/// 'Length' is also sometimes called 'arity' here; each tuple of a different
+/// length is a different, distinct type.
+///
+/// Tuples are *heterogeneous*. This means that each element of the tuple can
+/// have a different type. In that tuple above, it has the type:
+///
+/// ```rust,ignore
+/// (&'static str, i32, char)
+/// ```
+///
+/// Tuples are a *sequence*. This means that they can be accessed by position;
+/// this is called 'tuple indexing', and it looks like this:
+///
+/// ```rust
+/// let tuple = ("hello", 5, 'c');
+///
+/// assert_eq!(tuple.0, "hello");
+/// assert_eq!(tuple.1, 5);
+/// assert_eq!(tuple.2, 'c');
+/// ```
+///
+/// For more about tuples, see [the book](../../book/primitive-types.html#tuples).
+///
+/// # Trait implementations
 ///
 /// If every type inside a tuple implements one of the following
 /// traits, then a tuple itself also implements it.
 ///
-/// * `Clone`
-/// * `PartialEq`
-/// * `Eq`
-/// * `PartialOrd`
-/// * `Ord`
-/// * `Debug`
-/// * `Default`
-/// * `Hash`
+/// * [`Clone`]
+/// * [`PartialEq`]
+/// * [`Eq`]
+/// * [`PartialOrd`]
+/// * [`Ord`]
+/// * [`Debug`]
+/// * [`Default`]
+/// * [`Hash`]
+///
+/// [`Clone`]: ../clone/trait.Clone.html
+/// [`PartialEq`]: ../cmp/trait.PartialEq.html
+/// [`Eq`]: ../cmp/trait.Eq.html
+/// [`PartialOrd`]: ../cmp/trait.PartialOrd.html
+/// [`Ord`]: ../cmp/trait.Ord.html
+/// [`Debug`]: ../fmt/trait.Debug.html
+/// [`Default`]: ../default/trait.Default.html
+/// [`Hash`]: ../hash/trait.Hash.html
+///
+/// Due to a temporary restriction in Rust's type system, these traits are only
+/// implemented on tuples of arity 32 or less. In the future, this may change.
 ///
 /// # Examples
 ///
-/// Accessing elements of a tuple at specified indices:
+/// Basic usage:
 ///
 /// ```
-/// let x = ("colorless",  "green", "ideas", "sleep", "furiously");
-/// assert_eq!(x.3, "sleep");
+/// let tuple = ("hello", 5, 'c');
 ///
-/// let v = (3, 3);
-/// let u = (1, -5);
-/// assert_eq!(v.0 * u.0 + v.1 * u.1, -12);
+/// assert_eq!(tuple.0, "hello");
 /// ```
 ///
-/// Using traits implemented for tuples:
+/// Tuples are often used as a return type when you want to return more than
+/// one value:
 ///
 /// ```
-/// let a = (1, 2);
-/// let b = (3, 4);
-/// assert!(a != b);
+/// fn calculate_point() -> (i32, i32) {
+///     // Don't do a calculation, that's not the point of the example
+///     (4, 5)
+/// }
+///
+/// let point = calculate_point();
+///
+/// assert_eq!(point.0, 4);
+/// assert_eq!(point.1, 5);
+///
+/// // Combining this with patterns can be nicer.
 ///
-/// let c = b.clone();
-/// assert!(b == c);
+/// let (x, y) = calculate_point();
 ///
-/// let d : (u32, f32) = Default::default();
-/// assert_eq!(d, (0, 0.0f32));
+/// assert_eq!(x, 4);
+/// assert_eq!(y, 5);
 /// ```
 ///
 mod prim_tuple { }