From c6cca9cb81c72441c33b78fc74e3a5b33358334b Mon Sep 17 00:00:00 2001
From: Diggory Hardy <git@dhardy.name>
Date: Sun, 26 Mar 2023 17:52:45 +0100
Subject: [PATCH] StepRng: better documentation of outputs for other types
 (#1304)

---
 src/rngs/mock.rs | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/src/rngs/mock.rs b/src/rngs/mock.rs
index a1745a490dd..0d9e0f905c9 100644
--- a/src/rngs/mock.rs
+++ b/src/rngs/mock.rs
@@ -13,12 +13,23 @@ use rand_core::{impls, Error, RngCore};
 #[cfg(feature = "serde1")]
 use serde::{Serialize, Deserialize};
 
-/// A simple implementation of `RngCore` for testing purposes.
+/// A mock generator yielding very predictable output
 ///
 /// This generates an arithmetic sequence (i.e. adds a constant each step)
 /// over a `u64` number, using wrapping arithmetic. If the increment is 0
 /// the generator yields a constant.
 ///
+/// Other integer types (64-bit and smaller) are produced via cast from `u64`.
+///
+/// Other types are produced via their implementation of [`Rng`](crate::Rng) or
+/// [`Distribution`](crate::distributions::Distribution).
+/// Output values may not be intuitive and may change in future releases but
+/// are considered
+/// [portable](https://rust-random.github.io/book/portability.html).
+/// (`bool` output is true when bit `1u64 << 31` is set.)
+///
+/// # Example
+///
 /// ```
 /// use rand::Rng;
 /// use rand::rngs::mock::StepRng;
@@ -72,11 +83,12 @@ impl RngCore for StepRng {
 
 #[cfg(test)]
 mod tests {
+    #[cfg(any(feature = "alloc", feature = "serde1"))]
+    use super::StepRng;
+
     #[test]
     #[cfg(feature = "serde1")]
     fn test_serialization_step_rng() {
-        use super::StepRng;
-
         let some_rng = StepRng::new(42, 7);
         let de_some_rng: StepRng =
             bincode::deserialize(&bincode::serialize(&some_rng).unwrap()).unwrap();
@@ -84,4 +96,16 @@ mod tests {
         assert_eq!(some_rng.a, de_some_rng.a);
 
     }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    fn test_bool() {
+        use crate::{Rng, distributions::Standard};
+
+        // If this result ever changes, update doc on StepRng!
+        let rng = StepRng::new(0, 1 << 31);
+        let result: alloc::vec::Vec<bool> =
+            rng.sample_iter(Standard).take(6).collect();
+        assert_eq!(&result, &[false, true, false, true, false, true]);
+    }
 }