From 7c424a7f9b8e9ad02d4e16f7a210af54b46c8fdb Mon Sep 17 00:00:00 2001
From: Diggory Hardy <git@dhardy.name>
Date: Fri, 26 Jul 2024 10:39:17 +0100
Subject: [PATCH] Doc: Rng::random vs fill

---
 src/rng.rs | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/rng.rs b/src/rng.rs
index 9c015eddd41..9cea5fb20c6 100644
--- a/src/rng.rs
+++ b/src/rng.rs
@@ -73,7 +73,8 @@ pub trait Rng: RngCore {
     /// generated.
     ///
     /// For arrays of integers, especially for those with small element types
-    /// (< 64 bit), it will likely be faster to instead use [`Rng::fill`].
+    /// (< 64 bit), it will likely be faster to instead use [`Rng::fill`],
+    /// though note that generated values will differ.
     ///
     /// ```
     /// use rand::{thread_rng, Rng};
@@ -223,6 +224,10 @@ pub trait Rng: RngCore {
 
     /// Fill any type implementing [`Fill`] with random data
     ///
+    /// This method is implemented for types which may be safely reinterpreted
+    /// as an (aligned) `[u8]` slice then filled with random data. It is often
+    /// faster than using [`Rng::random`] but not value-equivalent.
+    ///
     /// The distribution is expected to be uniform with portable results, but
     /// this cannot be guaranteed for third-party implementations.
     ///