Rollup merge of #35613 - matthew-piziak:array-docs-trait-justification, r=steveklabnik

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.

Note: I'm dipping my toes in the water with a tiny PR. Especially looking for feedback on wording and style. Points of concern: appropriate level of top-level explanation; foreshadowing (is it appropriate to imply that we expect Rust's type system to eventually support size-generic arrays?); using `Foo` and `Bar` as type variables instead of e.g. `T` and `S`.

@peschkaj

1 files changed, 8 insertions, 3 deletions

diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index 84618ba2593..d31a5930376 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
 ///
 /// ```