Update documentation on generating arrays

Author: dhardy

src/distributions/mod.rs

@@ -289,13 +289,15 @@ impl<D, R, T> iter::TrustedLen for DistIter<D, R, T>
 /// * Wrapping integers (`Wrapping<T>`), besides the type identical to their
 ///   normal integer variants.
 ///
-/// The following aggregate types also implement the distribution `Standard` as
-/// long as their component types implement it:
+/// The `Standard` distribution also supports generation of the following
+/// compound types where all component types are supported:
 ///
-/// * Tuples and arrays: Each element of the tuple or array is generated
-///   independently, using the `Standard` distribution recursively.
-/// * `Option<T>` where `Standard` is implemented for `T`: Returns `None` with
-///   probability 0.5; otherwise generates a random `x: T` and returns `Some(x)`.
+/// *   Tuples (up to 12 elements): each element is generated sequentially.
+/// *   Arrays (up to 32 elements): each element is generated sequentially;
+///     see also [`Rng::fill`] which supports arbitrary array length for integer
+///     types and tends to be faster for `u32` and smaller types.
+/// *   `Option<T>` first generates a `bool`, and if true generates and returns
+///     `Some(value)` where `value: T`, otherwise returning `None`.
 ///
 /// ## Custom implementations
 ///

src/lib.rs

@@ -135,8 +135,6 @@ use distributions::uniform::{SampleUniform, UniformSampler, SampleBorrow};
 pub trait Rng: RngCore {
     /// Return a random value supporting the [`Standard`] distribution.
     ///
-    /// [`Standard`]: distributions::Standard
-    ///
     /// # Example
     ///
     /// ```
@@ -147,6 +145,28 @@ pub trait Rng: RngCore {
     /// println!("{}", x);
     /// println!("{:?}", rng.gen::<(f64, bool)>());
     /// ```
+    ///
+    /// # Arrays and tuples
+    ///
+    /// The `rng.gen()` method is able to generate arrays (up to 32 elements)
+    /// and tuples (up to 12 elements), so long as all element types can be
+    /// generated.
+    ///
+    /// For arrays of integers, especially for those with small element types
+    /// (< 64 bit), it will likely be faster to instead use [`Rng::fill`].
+    ///
+    /// ```
+    /// use rand::{thread_rng, Rng};
+    ///
+    /// let mut rng = thread_rng();
+    /// let tuple: (u8, i32, char) = rng.gen(); // arbitrary tuple support
+    ///
+    /// let arr1: [f32; 32] = rng.gen();        // array construction
+    /// let mut arr2 = [0u8; 128];
+    /// rng.fill(&mut arr2);                    // array fill
+    /// ```
+    ///
+    /// [`Standard`]: distributions::Standard
     #[inline]
     fn gen<T>(&mut self) -> T
     where Standard: Distribution<T> {