Enhance documentation with usage examples for random number generation utilities

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};
 

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;

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;

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;
 

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.