From c99faf7d0c0e0eaa90d2c171669b8369b3db8090 Mon Sep 17 00:00:00 2001
From: "J.A. de Jong - Redu-Sone B.V., ASCEE V.O.F" <j.a.dejong@ascee.nl>
Date: Wed, 29 Nov 2023 07:44:40 +0100
Subject: [PATCH] Some docs and bugfixes in siggen

---
 src/siggen.rs | 47 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 7 deletions(-)

diff --git a/src/siggen.rs b/src/siggen.rs
index 369f1ef..65a0423 100644
--- a/src/siggen.rs
+++ b/src/siggen.rs
@@ -1,3 +1,18 @@
+//! This module provide signal generators. 
+//!
+//! # Examples
+//!
+//! ## Create some white noise and print it.
+//!
+//! ```
+//! let mut wn = Siggen::newWhiteNoise();
+//! wn.setGain(0.1);
+//! wn.setMute(false);
+//! let mut sig = [0. ; 1024];
+//! wn.genSignal(&mut sig);
+//! println!("{:?}", &sig);
+//!
+//! ```
 use super::config::*;
 use super::filter::Filter;
 use pyo3::prelude::*;
@@ -5,9 +20,12 @@ use rand::prelude::*;
 use rand::rngs::ThreadRng;
 use rand_distr::StandardNormal;
 
-pub trait Source: Send {
+trait Source: Send {
+    /// Generate the 'pure' source signal. Output is placed inside the `sig` argument.
     fn genSignal_unscaled(&mut self, sig: &mut [Flt]);
+    /// Reset the source state, i.e. set phase to 0, etc
     fn reset(&mut self, fs: Flt);
+    /// Used to make the Siggen struct cloneable
     fn clone_dyn(&self) -> Box<dyn Source>;
 }
 impl Clone for Box<dyn Source> {
@@ -30,7 +48,7 @@ impl Source for WhiteNoise {
         sig.iter_mut()
             .for_each(|s| *s = thread_rng().sample(StandardNormal));
     }
-    fn reset(&mut self,_fs: Flt) {}
+    fn reset(&mut self, _fs: Flt) {}
     fn clone_dyn(&self) -> Box<dyn Source> {
         Box::new(self.clone())
     }
@@ -88,12 +106,14 @@ impl Source for Sine {
 
 /// Sweep signal
 
-
 #[derive(Clone)]
 /// Signal generator. Able to create acoustic output signals
 pub struct Siggen {
+    // The source dynamic signal. Noise, a sine wave, sweep, etc
     source: Box<dyn Source>,
+    // Filter applied to the source signal
     prefilter: Option<Box<dyn Filter>>,
+    // If set, no dynamic signal source output is given
     muted: bool,
     gain: Flt,
     DCOffset: Flt,
@@ -105,9 +125,20 @@ impl Siggen {
     pub fn setPreFilter(&mut self, pref: Option<Box<dyn Filter>>) {
         self.prefilter = pref.clone();
     }
+    /// Set the gain applied to the source signal
+    ///
+    /// * g: Gain value. Can be any float. If set to 0.0, the source is effectively muted. Only
+    /// using (setMute) is a more efficient way to do this.
+    pub fn setGain(&mut self, g: Flt) {
+        self.gain = g;
+    }
+    /// Create a white noise signal generator.
     pub fn newWhiteNoise() -> Siggen {
         Siggen::new(Box::new(WhiteNoise::new()))
     }
+    /// Create a sine wave signal generator
+    ///
+    /// * freq: Frequency of the sine wave in [Hz]
     pub fn newSineWave(freq: Flt) -> Siggen {
         Siggen::new(Box::new(Sine::new(freq)))
     }
@@ -138,7 +169,7 @@ impl Siggen {
     ///     - Gain is applied.
     ///     - Offset is applied (thus, no gain is applied to the DC offset).
     ///
-    fn genSignal(&mut self, sig: &mut [Flt]) {
+    pub fn genSignal(&mut self, sig: &mut [Flt]) {
         if self.muted {
             sig.iter_mut().for_each(|x| {
                 *x = 0.0;
@@ -162,9 +193,9 @@ impl Siggen {
     ///
     /// * fs: (New) Sampling frequency [Hz]
     ///
-    fn reset(&mut self, fs: Flt) {
+    pub fn reset(&mut self, fs: Flt) {
         self.source.reset(fs);
-        if let Some(f) = self.prefilter {
+        if let Some(f) = &mut self.prefilter {
             f.reset();
         }
     }
@@ -176,6 +207,8 @@ mod test {
 
     #[test]
     fn test_whitenoise() {
-        println!("{:?}", WhiteNoise::new().genSignal(10));
+        let mut t = &[0.; 10];
+        Siggen::newWiteNoise().genSignal(&mut t);
+        println!("{:?}", &t);
     }
 }