Tweak array docs

Fixes #29331.

1 files changed, 65 insertions, 21 deletions

diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index 2b92da6c684..fdc84467015 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -249,37 +249,58 @@ mod prim_pointer { }
 #[doc(primitive = "array")]
 //
 /// A fixed-size array, denoted `[T; N]`, for the element type, `T`, and the
-/// non-negative compile time constant size, `N`.
+/// non-negative compile-time constant size, `N`.
 ///
-/// Arrays values are created either with an explicit expression that lists
-/// each element: `[x, y, z]` or a repeat expression: `[x; N]`. The repeat
-/// expression requires that the element type is `Copy`.
+/// There are two syntactic forms for creating an array:
 ///
-/// The type `[T; N]` is `Copy` if `T: Copy`.
+/// * A list with each element, i.e. `[x, y, z]`.
+/// * A repeat expression `[x; N]`, which produces an array with `N` copies of `x`.
+///   The type of `x` must be [`Copy`][copy].
 ///
 /// Arrays of sizes from 0 to 32 (inclusive) implement the following traits if
 /// the element type allows it:
 ///
-/// - `Clone` (only if `T: Copy`)
-/// - `Debug`
-/// - `IntoIterator` (implemented for `&[T; N]` and `&mut [T; N]`)
-/// - `PartialEq`, `PartialOrd`, `Ord`, `Eq`
-/// - `Hash`
-/// - `AsRef`, `AsMut`
-/// - `Borrow`, `BorrowMut`
-/// - `Default`
-///
-/// This limitation to `N in 0..33` exists because Rust does not yet support
-/// generics over the size of an array type. `[Foo; 3]` and `[Bar; 3]` are
-/// instances of same generic type `[T; 3]`, but `[Foo; 3]` and `[Foo; 5]` are
+/// - [`Clone`][clone] (only if `T: Copy`)
+/// - [`Debug`][debug]
+/// - [`IntoIterator`][intoiterator] (implemented for `&[T; N]` and `&mut [T; N]`)
+/// - [`PartialEq`][partialeq], [`PartialOrd`][partialord], [`Eq`][eq], [`Ord`][ord]
+/// - [`Hash`][hash]
+/// - [`AsRef`][asref], [`AsMut`][asmut]
+/// - [`Borrow`][borrow], [`BorrowMut`][borrowmut]
+/// - [`Default`][default]
+///
+/// This limitation on the size `N` exists because Rust does not yet support
+/// code that is generic over the size of an array type. `[Foo; 3]` and `[Bar; 3]`
+/// are instances of same generic type `[T; 3]`, but `[Foo; 3]` and `[Foo; 5]` are
 /// entirely different types. As a stopgap, trait implementations are
-/// statically generated for `N in 0..33`.
+/// statically generated up to size 32.
 ///
-/// Arrays coerce to [slices (`[T]`)][slice], so their methods can be called on
-/// arrays. Slices are dynamic and do not coerce to arrays; consequently more
-/// methods are defined on `slice` where they support both types.
+/// Arrays of *any* size are [`Copy`][copy] if the element type is `Copy`. This
+/// works because the `Copy` trait is specially known to the compiler.
+///
+/// Arrays coerce to [slices (`[T]`)][slice], so a slice method may be called on
+/// an array. Indeed, this provides most of the API for working with arrays.
+/// Slices have a dynamic size and do not coerce to arrays.
+///
+/// There is no way to move elements out of an array. See [`mem::replace`][replace]
+/// for an alternative.
 ///
 /// [slice]: primitive.slice.html
+/// [copy]: marker/trait.Copy.html
+/// [clone]: clone/trait.Clone.html
+/// [debug]: fmt/trait.Debug.html
+/// [intoiterator]: iter/trait.IntoIterator.html
+/// [partialeq]: cmp/trait.PartialEq.html
+/// [partialord]: cmp/trait.PartialOrd.html
+/// [eq]: cmp/trait.Eq.html
+/// [ord]: cmp/trait.Ord.html
+/// [hash]: hash/trait.Hash.html
+/// [asref]: convert/trait.AsRef.html
+/// [asmut]: convert/trait.AsMut.html
+/// [borrow]: borrow/trait.Borrow.html
+/// [borrowmut]: borrow/trait.BorrowMut.html
+/// [default]: default/trait.Default.html
+/// [replace]: mem/fn.replace.html
 ///
 /// # Examples
 ///
@@ -295,7 +316,30 @@ mod prim_pointer { }
 /// for x in &array {
 ///     print!("{} ", x);
 /// }
+/// ```
+///
+/// An array itself is not iterable:
+///
+/// ```ignore
+/// let array: [i32; 3] = [0; 3];
+///
+/// for x in array { }
+/// // error: the trait bound `[i32; 3]: std::iter::Iterator` is not satisfied
+/// ```
 ///
+/// The solution is to coerce the array to a slice by calling a slice method:
+///
+/// ```
+/// # let array: [i32; 3] = [0; 3];
+/// for x in array.iter() { }
+/// ```
+///
+/// If the array has 32 or fewer elements (see above), you can also use the
+/// array reference's `IntoIterator` implementation:
+///
+/// ```
+/// # let array: [i32; 3] = [0; 3];
+/// for x in &array { }
 /// ```
 ///
 mod prim_array { }