From 87cd605d73060181eb5a8b3129028b5d3ef6f114 Mon Sep 17 00:00:00 2001
From: Jamie Hardt <jamiehardt@me.com>
Date: Thu, 15 Aug 2024 01:32:46 -0700
Subject: [PATCH] More documentation, WhiteNoise creation option.

---
 src/source/noise.rs         | 25 +++++++++++++++++++------
 src/source/test_waveform.rs |  5 +++--
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/src/source/noise.rs b/src/source/noise.rs
index dfee917..04b450e 100644
--- a/src/source/noise.rs
+++ b/src/source/noise.rs
@@ -1,3 +1,6 @@
+//! Noise sources.
+//!
+//!
 use crate::Source;
 
 use super::SeekError;
@@ -5,19 +8,20 @@ use super::SeekError;
 use rand::rngs::SmallRng;
 use rand::{RngCore, SeedableRng};
 
-/// Create a new white noise source.
+/// Create a new `WhiteNoise` noise source.
 #[inline]
 pub fn white(sample_rate: cpal::SampleRate) -> WhiteNoise {
     WhiteNoise::new(sample_rate)
 }
 
-/// Create a new pink noise source.
+/// Create a new `PinkNoise` noise source.
 #[inline]
 pub fn pink(sample_rate: cpal::SampleRate) -> PinkNoise {
     PinkNoise::new(sample_rate)
 }
 
-/// Generates an infinite stream of random samples in [=1.0, 1.0]
+/// Generates an infinite stream of random samples in [-1.0, 1.0]. This source generates random
+/// samples as provided by the `rand::rngs::SmallRng` randomness source.
 #[derive(Clone, Debug)]
 pub struct WhiteNoise {
     sample_rate: cpal::SampleRate,
@@ -25,7 +29,15 @@ pub struct WhiteNoise {
 }
 
 impl WhiteNoise {
-    /// Create a new white noise generator.
+    /// Create a new white noise generator, seeding the RNG with `seed`.
+    pub fn new_with_seed(sample_rate: cpal::SampleRate, seed: u64) -> Self {
+        Self {
+            sample_rate,
+            rng: SmallRng::seed_from_u64(seed),
+        }
+    }
+
+    /// Create a new white noise generator, seeding the RNG with system entropy.
     pub fn new(sample_rate: cpal::SampleRate) -> Self {
         Self {
             sample_rate,
@@ -73,9 +85,10 @@ impl Source for WhiteNoise {
     }
 }
 
-// https://www.musicdsp.org/en/latest/Filters/76-pink-noise-filter.html
-//
 /// Generate an infinite stream of pink noise samples in [-1.0, 1.0].
+///
+/// The output of this source is the result of taking the output of the `WhiteNoise` source and
+/// filtering it according to a weighted-sum of seven FIR filters after [Paul Kellett](https://www.musicdsp.org/en/latest/Filters/76-pink-noise-filter.html).
 pub struct PinkNoise {
     noise: WhiteNoise,
     b: [f32; 7],
diff --git a/src/source/test_waveform.rs b/src/source/test_waveform.rs
index 1b2214b..b9615ae 100644
--- a/src/source/test_waveform.rs
+++ b/src/source/test_waveform.rs
@@ -1,7 +1,8 @@
 //! Generator sources for various periodic test waveforms.
 //!
-//! This module provides several periodic, deterministic waveforms for testing other sources. Every
-//! source oscillates in the codomain `[-1.0f32, 1.0f32]`.
+//! This module provides several periodic, deterministic waveforms for testing other sources and
+//! for simple additive sound synthesis. Every source is monoaural and in the codomain `[-1.0f32,
+//! 1.0f32]` 
 //!
 //! # Example
 //!