From 965b83e54d07804cd0e3988ff663171fc34442c3 Mon Sep 17 00:00:00 2001
From: Pete Jemian <prjemian@gmail.com>
Date: Mon, 2 Sep 2019 15:25:45 -0500
Subject: [PATCH] DOC #240

---
 apstools/synApps_ophyd/calcout.py | 104 ++++++++++++++++++++++++++--
 apstools/synApps_ophyd/swait.py   | 109 ++++++++++++++++++++++++++++--
 2 files changed, 205 insertions(+), 8 deletions(-)

diff --git a/apstools/synApps_ophyd/calcout.py b/apstools/synApps_ophyd/calcout.py
index 1e1dd8052..9f38a1e58 100644
--- a/apstools/synApps_ophyd/calcout.py
+++ b/apstools/synApps_ophyd/calcout.py
@@ -192,7 +192,33 @@ def reset(self):
 
 
 def _setup_peak_calcout_(calc, desc, calcout, ref_signal, center=0, width=1, scale=1, noise=0.05):
-    """internal: setup that is common to both Gaussian and Lorentzian calcout"""
+    """
+    internal: setup that is common to both Gaussian and Lorentzian calcouts
+    
+    PARAMETERS
+
+    calcout : object
+        instance of :class:`CalcoutRecord`
+
+    ref_signal : object
+        instance of :class:`EpicsSignal` used as $A$
+
+    center : float
+        $B$, 
+        default = 0
+
+    width : float
+        $C$,
+        default = 1
+
+    scale : float
+        $D$,
+        default = 1
+
+    noise : float
+        $E$,
+        default = 0.05
+    """
     # to add a noisy background will need another calc
     assert(isinstance(calcout, CalcoutRecord))
     assert(isinstance(ref_signal, EpicsSignal))
@@ -214,7 +240,35 @@ def _setup_peak_calcout_(calc, desc, calcout, ref_signal, center=0, width=1, sca
 
 
 def setup_gaussian_calcout(calcout, ref_signal, center=0, width=1, scale=1, noise=0.05):
-    """setup calcout for noisy Gaussian"""
+    """
+    setup calcout for noisy Gaussian
+    
+    calculation: $D*(0.95+E*RNDM)/exp(((A-B)/C)^2)$
+    
+    PARAMETERS
+
+    calcout : object
+        instance of :class:`CalcoutRecord`
+
+    ref_signal : object
+        instance of :class:`EpicsSignal` used as $A$
+
+    center : float
+        $B$, 
+        default = 0
+
+    width : float
+        $C$,
+        default = 1
+
+    scale : float
+        $D$,
+        default = 1
+
+    noise : float
+        $E$,
+        default = 0.05
+    """
     _setup_peak_calcout_(
         "D*(0.95+E*RNDM)/exp(((A-b)/c)^2)",
         "noisy Gaussian curve", 
@@ -226,14 +280,39 @@ def setup_gaussian_calcout(calcout, ref_signal, center=0, width=1, scale=1, nois
         noise=noise)
 
 
-def setup_lorentzian_calcout(calcout, ref_signal, center=0, width=1, scale=1, noise=0.05):
+def setup_lorentzian_calcout(calcout, ref_signal, 
+                             center=0, width=1, scale=1, noise=0.05):
     """
     setup calcout record for noisy Lorentzian
     
+    calculation: $D*(0.95+E*RNDM)/(1+((A-B)/C)^2)$
+    
     PARAMETERS
+
+    calcout : object
+        instance of :class:`CalcoutRecord`
+
+    ref_signal : object
+        instance of :class:`EpicsSignal` used as $A$
+
+    center : float
+        $B$, 
+        default = 0
+
+    width : float
+        $C$,
+        default = 1
+
+    scale : float
+        $D$,
+        default = 1
+
+    noise : float
+        $E$,
+        default = 0.05
     """
     _setup_peak_calcout_(
-        "D*(0.95+E*RNDM)/(1+((A-b)/c)^2)", 
+        "D*(0.95+E*RNDM)/(1+((A-B)/C)^2)", 
         "noisy Lorentzian curve", 
         calcout, 
         ref_signal, 
@@ -246,6 +325,23 @@ def setup_lorentzian_calcout(calcout, ref_signal, center=0, width=1, scale=1, no
 def setup_incrementer_calcout(calcout, scan=None, limit=100000):
     """
     setup calcout record as an incrementer
+
+    PARAMETERS
+
+    calcout : object
+        instance of :class:`CalcoutRecord`
+
+    scan : text or int or None
+        any of the EPICS record `.SCAN` values, 
+        or the index number of the value,
+        set to default if `None`,
+        default: `.1 second`
+
+    limit : int or None
+        set the incrementer back to zero 
+        when this number is reached (or passed),
+        default: 100000
+
     """
     # consider a noisy background, as well (needs a couple calcs)
     scan = scan or ".1 second"
diff --git a/apstools/synApps_ophyd/swait.py b/apstools/synApps_ophyd/swait.py
index 299b33a66..cdfd2ba81 100644
--- a/apstools/synApps_ophyd/swait.py
+++ b/apstools/synApps_ophyd/swait.py
@@ -195,7 +195,33 @@ def setup_random_number_swait(swait, **kw):
 
 
 def _setup_peak_swait_(calc, desc, swait, ref_signal, center=0, width=1, scale=1, noise=0.05):
-    """internal: setup that is common to both Gaussian and Lorentzian swaits"""
+    """
+    internal: setup that is common to both Gaussian and Lorentzian swaits
+    
+    PARAMETERS
+
+    swait : object
+        instance of :class:`SwaitRecord`
+
+    ref_signal : object
+        instance of :class:`EpicsSignal` used as $A$
+
+    center : float
+        $B$, 
+        default = 0
+
+    width : float
+        $C$,
+        default = 1
+
+    scale : float
+        $D$,
+        default = 1
+
+    noise : float
+        $E$,
+        default = 0.05
+    """
     # consider a noisy background, as well (needs a couple calcs)
     assert(isinstance(swait, SwaitRecord))
     assert(isinstance(ref_signal, EpicsSignal))
@@ -217,7 +243,35 @@ def _setup_peak_swait_(calc, desc, swait, ref_signal, center=0, width=1, scale=1
 
 
 def setup_gaussian_swait(swait, ref_signal, center=0, width=1, scale=1, noise=0.05):
-    """setup swait for noisy Gaussian"""
+    """
+    setup swait for noisy Gaussian
+    
+    calculation: $D*(0.95+E*RNDM)/exp(((A-B)/C)^2)$
+    
+    PARAMETERS
+
+    swait : object
+        instance of :class:`SwaitRecord`
+
+    ref_signal : object
+        instance of :class:`EpicsSignal` used as $A$
+
+    center : float
+        $B$, 
+        default = 0
+
+    width : float
+        $C$,
+        default = 1
+
+    scale : float
+        $D$,
+        default = 1
+
+    noise : float
+        $E$,
+        default = 0.05
+    """
     _setup_peak_swait_(
         "D*(0.95+E*RNDM)/exp(((A-b)/c)^2)",
         "noisy Gaussian curve", 
@@ -230,7 +284,35 @@ def setup_gaussian_swait(swait, ref_signal, center=0, width=1, scale=1, noise=0.
 
 
 def setup_lorentzian_swait(swait, ref_signal, center=0, width=1, scale=1, noise=0.05):
-    """setup swait record for noisy Lorentzian"""
+    """
+    setup swait record for noisy Lorentzian
+    
+    calculation: $D*(0.95+E*RNDM)/(1+((A-B)/C)^2)$
+    
+    PARAMETERS
+
+    swait : object
+        instance of :class:`SwaitRecord`
+
+    ref_signal : object
+        instance of :class:`EpicsSignal` used as $A$
+
+    center : float
+        $B$, 
+        default = 0
+
+    width : float
+        $C$,
+        default = 1
+
+    scale : float
+        $D$,
+        default = 1
+
+    noise : float
+        $E$,
+        default = 0.05
+    """
     _setup_peak_swait_(
         "D*(0.95+E*RNDM)/(1+((A-b)/c)^2)", 
         "noisy Lorentzian curve", 
@@ -243,7 +325,26 @@ def setup_lorentzian_swait(swait, ref_signal, center=0, width=1, scale=1, noise=
 
 
 def setup_incrementer_swait(swait, scan=None, limit=100000):
-    """setup swait record as an incrementer"""
+    """
+    setup swait record as an incrementer
+
+    PARAMETERS
+
+    swait : object
+        instance of :class:`SwaitRecord`
+
+    scan : text or int or None
+        any of the EPICS record `.SCAN` values, 
+        or the index number of the value,
+        set to default if `None`,
+        default: `.1 second`
+
+    limit : int or None
+        set the incrementer back to zero 
+        when this number is reached (or passed),
+        default: 100000
+
+    """
     # consider a noisy background, as well (needs a couple calcs)
     scan = scan or ".1 second"
     swait.reset()