Properly document tuples

Fixes #29339

2 files changed, 66 insertions, 45 deletions

diff --git a/src/libcore/tuple.rs b/src/libcore/tuple.rs
index 4127e182e1d..abaabfd129b 100644
--- a/src/libcore/tuple.rs
+++ b/src/libcore/tuple.rs
@@ -8,24 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! A finite heterogeneous sequence, `(T, U, ..)`
-//!
-//! To access a single element of a tuple one can use the `.0`
-//! field access syntax.
-//!
-//! Indexing starts from zero, so `.0` returns first value, `.1`
-//! returns second value, and so on. In general, a tuple with *N*
-//! elements has field accessors from 0 to *N* - 1.
-//!
-//! If every type inside a tuple implements one of the following
-//! traits, then a tuple itself also implements it.
-//!
-//! * `Clone`
-//! * `PartialEq`
-//! * `Eq`
-//! * `PartialOrd`
-//! * `Ord`
-//! * `Default`
+// See src/libstd/primitive_docs.rs for documentation.
 
 use clone::Clone;
 use cmp::*;
diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index ed59c51b0f0..2be8c41a496 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -357,50 +357,88 @@ 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');
+/// ```
+///
+/// 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
 ///
 /// # 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 { }