add documentation to the class

Author: AlvaroEzq

images/RecoverSignalProcess_addedAmplIntegral.png

@@ -21,43 +21,103 @@
  *************************************************************************/
 
 /////////////////////////////////////////////////////////////////////////
-/// Write the process description Here
-///
-/// ### Parameters
-/// Describe any parameters this process receives:
-/// * **parameter1**: This parameter ...
-/// * **parameter2**: This parameter is ...
+/// This class is a process to recover the signals that saturated the ADC.
+/// The process uses a fit to recover the signal lost information. If the fit
+/// is successful, the points of the signal that are saturating are replaced
+/// by the fit values at those bins.
+/// \htmlonly <style>div.image img[src="RecoverSignalProcess_eventRecovered.png"]{width:350px;}</style> \endhtmlonly
 ///
+/// The idea of the process is to recover the signal information that is lost
+/// when the signal saturates the ADC in order to continue the analysis of the
+/// event as if the signal was not saturated at all. For example, here is the 
+/// comparison in the spectrum of the observable ThresholdIntegral of the
+/// TRestRawSignalAnalysisProcess before (red) and after (blue) applying this
+/// TRestRawSignalRecoverSaturationProcess:
+/// \htmlonly <style>div.image img[src="RecoverSignalProcess_spectrumComparison.png"]{width:350px;}</style> \endhtmlonly
 ///
-/// ### Examples
-/// Give examples of usage and RML descriptions that can be tested.
+/// ### Fitting function
+/// The fitting function is fixed (hardcoded) to the AGET response function
+/// (without the sin) times a logistic function:
 /// \code
-///     <WRITE A CODE EXAMPLE HERE>
+/// [0]+[1]*TMath::Exp(-3. * (x-[3])/[2]) * 
+/// (x-[3])/[2] * (x-[3])/[2] * (x-[3])/[2] / 
+/// (1+TMath::Exp(-10000*(x-[3])))
+///
+/// [0] = "Baseline",
+/// [1] = "Amplitude",
+/// [2] = "ShapingTime",
+/// [3] = "PeakPosition"
 /// \endcode
+/// \htmlonly <style>div.image img[src="RecoverSignalProcess_signalFit.png"]{width:350px;}</style> \endhtmlonly
+///
+///
+/// ### Parameters
+/// The default behaviour is to process only the saturated signals, but it
+/// can be configured to process all signals in the event
+/// (using the fProcessAllSignals parameter). The saturated signals are
+/// identified by a minimun number of bins (fMinSaturatedBins) that must 
+/// have the maximum value of the signal and by a threshold value which
+/// this saturating value must exceed (fMinSaturationValue).
+///
+/// The fit can be configured with the fBaseLineRange and fFitRange parameters.
+/// The baseline range is used to calculate the baseline of the signal and fix
+/// that parameter in the fit. This will make the fit faster and more reliable.
+/// The fit range is the range of bins to fit the signal. If not provided, the
+/// whole signal will be used.
 ///
-/// ### Running pipeline example
-/// Add the examples to a pipeline to guarantee the code will be running
-/// on future framework upgrades.
+/// To debug the process, you may use _debug_ or _extreme_ verbose levels.
+/// In the extreme level, a canvas will be created to draw the signal and
+/// the fit for each processed signal of the event. In the debug level, the
+/// fit result will be printed in the console but no canvas will be created.
 ///
+/// * **minSaturatedBins**: Minimum number of saturated bins to consider a signal as saturated.
+/// Default is 3.
+/// * **minSaturationValue**: Threshold to consider a maximum value of the signal as possible saturation.
+/// Default is 0.
+/// * **baseLineRange**: Range of bins to calculate the baseline and fix that parameter in the fit.
+/// * **fitRange**: Range of bins to fit the signal.
+/// * **processAllSignals**: If false (default), only signals considered as saturated will be processed.
+/// If true, all signals will be processed.
+/// * **nBinsIfNotSaturated**: Number of bins to consider as 'saturated' if the signal is not saturated.
+/// This is used when fProcessAllSignals is true to set the 'saturated' bins.
 ///
-/// Please, add any figure that may help to ilustrate the process
+/// ### Observables
+/// The process will add the following observables to the event:
+/// * **addedAmplitude**: Sum of the extra amplitude (newamplitude - previousamplitude) of the
+/// recovered saturated signals of the event.
+/// * **addedIntegral**: Sum of the extra integral (sum of newvalue-previousvalue of the saturated bins)
+/// of the recovered saturated signals of the event.
+/// * **saturatedSignals**: number of signals of the event detected as saturated.
+/// * **recoveredSignals**: number of signals of the event detected as saturated and that have been
+/// modified by the fitted pulse. It is always <=saturatedSignals. If it is less, it means that
+/// the fit values of the saturated bins of the those signals were lower than the original value
+/// of the signal so they are not replaced and those signals has not been recovered.
+/// \htmlonly <style>div.image img[src="RecoverSignalProcess_addedAmplIntegral.png"]{width:350px;}</style> \endhtmlonly
 ///
-/// \htmlonly <style>div.image img[src="trigger.png"]{width:500px;}</style> \endhtmlonly
-/// ![An ilustration of the trigger definition](trigger.png)
 ///
-/// The png image should be uploaded to the ./images/ directory
+/// ### Examples
+/// Give examples of usage and RML descriptions that can be tested.
+/// \code
+///    <addProcess type="TRestRawSignalRecoverSaturationProcess" name="recSat" value="ON" verboseLevel="info" observable="all">
+///        <parameter name="minSaturatedBins" value="3" />
+///        <parameter name="minSaturationValue" value="3500" />
+///        <parameter name="baseLineRange" value="(20,150)" />
+///        <parameter name="fitRange" value="(150,300)" />
+///    </addProcess>
+/// \endcode
+///
 ///
 ///----------------------------------------------------------------------
 ///
 /// REST-for-Physics - Software for Rare Event Searches Toolkit
 ///
 /// History of developments:
 ///
-/// YEAR-Month: First implementation of TRestRawSignalRecoverSaturationProcess
-/// WRITE YOUR FULL NAME
+/// 2025-Jan: First implementation of TRestRawSignalRecoverSaturationProcess
+/// Álvaro Ezquerro
 ///
 /// \class TRestRawSignalRecoverSaturationProcess
-/// \author: TODO. Write full name and e-mail:        aezquerro
+/// \author: aezquerro
 ///
 /// <hr>
 ///