provide additional justification for array interface design

Explain why Rust does not implement traits for large arrays.

Explain why most methods are implemented on slices rather than arrays.

1 files changed, 8 insertions, 3 deletions

diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index de891ea8918..fc838768322 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -269,13 +269,18 @@ mod prim_pointer { }
 /// - `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
+/// entirely different types. As a stopgap, trait implementations are
+/// statically generated for `N in 0..33`.
+///
 /// Arrays coerce to [slices (`[T]`)][slice], so their methods can be called on
-/// arrays.
+/// arrays. Slices are dynamic and do not coerce to arrays; consequently more
+/// methods are defined on `slice` where they support both types.
 ///
 /// [slice]: primitive.slice.html
 ///
-/// Rust does not currently support generics over the size of an array type.
-///
 /// # Examples
 ///
 /// ```