Add more docs for random number generators

Author: wigging

.swiftlint.yml

@@ -5,6 +5,8 @@ disabled_rules:
   - identifier_name
   - file_length
   - type_body_length
+  - large_tuple
+  - legacy_random
 
 excluded:
   - .build

Sources/Numerix/RandomModule/Wyrand.swift

@@ -1,10 +1,9 @@
 /*
-Wyrand pseudorandom number generator (PRNG) based on wyrand and wyhash functions by Wang Yi.
+Wyrand pseudorandom number generator (PRNG).
+Based on the wyrand and wyhash functions by Wang Yi.
 
-Original code for wyrand and wyhash functions
+References:
 https://github.com/wangyi-fudan/wyhash
-
-Also see Daniel Lemire's article about wyhash
 https://lemire.me/blog/2019/03/19/the-fastest-conventional-random-number-generator-that-can-pass-big-crush/
 */
 

Sources/Numerix/RandomModule/Xoroshiro.swift

@@ -1,5 +1,9 @@
 /*
 Xoroshiro128+ and Xoroshiro128++ pseudorandom number generators (PRNGs).
+
+References:
+https://prng.di.unimi.it
+https://prng.di.unimi.it/xoroshiro128plus.c
 */
 
 import Accelerate
@@ -8,16 +12,20 @@ func rotl(_ x: UInt64, _ k: Int) -> UInt64 {
     (x &<< k) | (x &>> (64 &- k))
 }
 
-/// Xoroshiro128+ is a 64-bit pseudorandom number generator (PRNG) for double-precision values.
+/// Xoroshiro128+ is a 64-bit pseudorandom number generator (PRNG) for floating-point numbers.
 public struct Xoroshiro128Plus: RandomNumberGenerator {
     private var state: (UInt64, UInt64)
 
+    /// Initialize the state of the generator.
+    /// - Parameter seed: Seed with two 64-bit unsigned integers.
     public init(seed: (UInt64, UInt64)? = nil) {
         let a = UInt64.random(in: 0..<UInt64.max)
         let b = UInt64.random(in: 0..<UInt64.max)
         state = seed ?? (a, b)
     }
 
+    /// Generate a random 64-bit unsigned integer.
+    /// - Returns: Random 64-bit unsigned integer value.
     public mutating func next() -> UInt64 {
         let s0 = state.0
         var s1 = state.1
@@ -30,24 +38,28 @@ public struct Xoroshiro128Plus: RandomNumberGenerator {
         return result
     }
 
-    /// Generate a random double-precision value from a uniform distribution over [0, 1) which includes zero but
+    /// Generate a random double-precision value from a uniform distribution in [0, 1) which includes zero but
     /// excludes one.
     /// - Returns: Random double-precision value.
     public mutating func next() -> Double {
         Double(next() >> 11) * 0x1.0p-53
     }
 }
 
-/// Xoroshiro128++ is a 64-bit pseudorandom number generator (PRNG) for double-precision values.
+/// Xoroshiro128++ is a 64-bit pseudorandom number generator (PRNG) for floating-point numbers.
 public struct Xoroshiro128PlusPlus: RandomNumberGenerator {
     private var state: (UInt64, UInt64)
 
+    /// Initialize the state of the generator.
+    /// - Parameter seed: Seed with two 64-bit unsigned integers.
     public init(seed: (UInt64, UInt64)? = nil) {
         let a = UInt64.random(in: 0..<UInt64.max)
         let b = UInt64.random(in: 0..<UInt64.max)
         state = seed ?? (a, b)
     }
 
+    /// Generate a random 64-bit unsigned integer.
+    /// - Returns: Random 64-bit unsigned integer value.
     public mutating func next() -> UInt64 {
         let s0 = state.0
         var s1 = state.1
@@ -59,8 +71,8 @@ public struct Xoroshiro128PlusPlus: RandomNumberGenerator {
 
         return result
     }
-    
-    /// Generate a random double-precision value from a uniform distribution over [0, 1) which includes zero but
+
+    /// Generate a random double-precision value from a uniform distribution in [0, 1) which includes zero but
     /// excludes one.
     /// - Returns: Random double-precision value.
     public mutating func next() -> Double {

Sources/Numerix/RandomModule/Xoshiro.swift

@@ -1,17 +1,25 @@
 /*
 Xoshiro128+ pseudorandom number generator (PRNG).
+
+References:
+https://prng.di.unimi.it
+https://prng.di.unimi.it/xoshiro128plus.c
 */
 
 import Accelerate
 
-/// Xoshiro128+ is a 32-bit pseudorandom number generator (PRNG) for single-precision (floating point) values.
+/// Xoshiro128+ is a 32-bit pseudorandom number generator (PRNG) for single-precision (32-bit floating point) numbers.
 public struct Xoshiro128Plus {
     private var state: (UInt32, UInt32, UInt32, UInt32)
 
+    /// Initialize the state of the generator.
+    /// - Parameter seed: Seed with four 32-bit unsigned integers.
     public init(seed: (UInt32, UInt32, UInt32, UInt32)? = nil) {
         state = seed ?? (arc4random(), arc4random(), arc4random(), arc4random())
     }
 
+    /// Generate a random 32-bit unsigned integer.
+    /// - Returns: Random 32-bit unsigned integer value.
     public mutating func next() -> UInt32 {
         let result = state.0 &+ state.3
         let t = state.1 << 9
@@ -28,7 +36,7 @@ public struct Xoshiro128Plus {
         return result
     }
 
-    /// Generate a random single-precision value from a uniform distribution over [0, 1) which includes zero but
+    /// Generate a random single-precision value from a uniform distribution in [0, 1) which includes zero but
     /// excludes one.
     /// - Returns: Random single-precision value.
     public mutating func next() -> Float {