From 18b9eef0635537033142d24a24ea3da654c84c54 Mon Sep 17 00:00:00 2001
From: Palash Tyagi <23239946+Magnus167@users.noreply.github.com>
Date: Sun, 3 Aug 2025 16:45:00 +0100
Subject: [PATCH] Enhance documentation with usage examples for random number
 generation utilities

---
 src/random/crypto.rs      | 10 ++++++++++
 src/random/mod.rs         | 15 +++++++++++++++
 src/random/prng.rs        |  8 ++++++++
 src/random/random_core.rs |  8 ++++++++
 src/random/seq.rs         |  8 ++++++++
 5 files changed, 49 insertions(+)

diff --git a/src/random/crypto.rs b/src/random/crypto.rs
index 678493f..4f0d694 100644
--- a/src/random/crypto.rs
+++ b/src/random/crypto.rs
@@ -1,3 +1,13 @@
+//! Cryptographically secure random number generator.
+//!
+//! On Unix systems this reads from `/dev/urandom`; on Windows it uses the
+//! system's preferred CNG provider.
+//!
+//! ```
+//! use rustframe::random::{crypto_rng, Rng};
+//! let mut rng = crypto_rng();
+//! let _v = rng.next_u64();
+//! ```
 #[cfg(unix)]
 use std::{fs::File, io::Read};
 
diff --git a/src/random/mod.rs b/src/random/mod.rs
index b40a343..2d0951c 100644
--- a/src/random/mod.rs
+++ b/src/random/mod.rs
@@ -1,3 +1,18 @@
+//! Random number generation utilities.
+//!
+//! Provides both a simple pseudo-random generator [`Prng`](crate::random::Prng) and a
+//! cryptographically secure alternative [`CryptoRng`](crate::random::CryptoRng). The
+//! [`SliceRandom`](crate::random::SliceRandom) trait offers shuffling of slices using any RNG
+//! implementing [`Rng`](crate::random::Rng).
+//!
+//! ```
+//! use rustframe::random::{rng, SliceRandom};
+//!
+//! let mut rng = rng();
+//! let mut data = [1, 2, 3, 4];
+//! data.shuffle(&mut rng);
+//! assert_eq!(data.len(), 4);
+//! ```
 pub mod crypto;
 pub mod prng;
 pub mod random_core;
diff --git a/src/random/prng.rs b/src/random/prng.rs
index 067d163..5d82080 100644
--- a/src/random/prng.rs
+++ b/src/random/prng.rs
@@ -1,3 +1,11 @@
+//! A tiny XorShift64-based pseudo random number generator.
+//!
+//! ```
+//! use rustframe::random::{rng, Rng};
+//! let mut rng = rng();
+//! let x = rng.next_u64();
+//! assert!(x >= 0);
+//! ```
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use crate::random::Rng;
diff --git a/src/random/random_core.rs b/src/random/random_core.rs
index 5db5617..37a5fb9 100644
--- a/src/random/random_core.rs
+++ b/src/random/random_core.rs
@@ -1,3 +1,11 @@
+//! Core traits for random number generators and sampling ranges.
+//!
+//! ```
+//! use rustframe::random::{rng, Rng};
+//! let mut r = rng();
+//! let value: f64 = r.random_range(0.0..1.0);
+//! assert!(value >= 0.0 && value < 1.0);
+//! ```
 use std::f64::consts::PI;
 use std::ops::Range;
 
diff --git a/src/random/seq.rs b/src/random/seq.rs
index 8df863f..760450e 100644
--- a/src/random/seq.rs
+++ b/src/random/seq.rs
@@ -1,3 +1,11 @@
+//! Extensions for shuffling slices with a random number generator.
+//!
+//! ```
+//! use rustframe::random::{rng, SliceRandom};
+//! let mut data = [1, 2, 3];
+//! data.shuffle(&mut rng());
+//! assert_eq!(data.len(), 3);
+//! ```
 use crate::random::Rng;
 
 /// Trait for randomizing slices.