improve doxygen documentation of PPrepFourier.*

src/classes/PPrepFourier.cpp

@@ -35,7 +35,10 @@
 // Constructor
 //--------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * \brief Default constructor that initializes to default values.
+ *
+ * Sets background range to unused (-1, -1) and packing to 1 (no rebinning).
+ * Background values and data must be set separately using setter methods.
  */
 PPrepFourier::PPrepFourier()
 {
@@ -48,7 +51,15 @@ PPrepFourier::PPrepFourier()
 // Constructor
 //--------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * \brief Full constructor that initializes all configuration parameters.
+ *
+ * Creates a PPrepFourier instance with complete configuration. Background
+ * can be specified either via range (for automatic calculation) or via
+ * explicit values (one per data set to be added later).
+ *
+ * \param packing Rebinning factor (1=no rebinning, N=combine N bins)
+ * \param bkgRange Background range [start, end] in bins (-1 if not used)
+ * \param bkg Vector of explicit background values (one per data set)
  */
 PPrepFourier::PPrepFourier(const Int_t packing, const Int_t *bkgRange, PDoubleVector bkg) :
   fPacking(packing)
@@ -61,7 +72,10 @@ PPrepFourier::PPrepFourier(const Int_t packing, const Int_t *bkgRange, PDoubleVe
 // Destructor
 //--------------------------------------------------------------------------
 /**
- * <p>Destructor.
+ * \brief Destructor that cleans up internal data structures.
+ *
+ * Clears both raw data and processed data vectors. Note that TH1F objects
+ * returned by GetData() are owned by the caller and not cleaned up here.
  */
 PPrepFourier::~PPrepFourier()
 {
@@ -73,9 +87,14 @@ PPrepFourier::~PPrepFourier()
 // SetBkgRange
 //--------------------------------------------------------------------------
 /**
- * <p>set the background range.
+ * \brief Sets the background range for automatic background calculation.
  *
- * \param bkgRange array with background range
+ * Specifies the bin range [start, end] for calculating background by averaging.
+ * Values of -1 indicate that background range is not used (explicit background
+ * values should be provided instead). Validates that both values are ≥-1 and
+ * prints warnings if invalid values are encountered.
+ *
+ * \param bkgRange Array [start, end] with background bin range (both must be ≥-1)
  */
 void PPrepFourier::SetBkgRange(const Int_t *bkgRange)
 {
@@ -116,12 +135,16 @@ void PPrepFourier::SetBkgRange(const Int_t *bkgRange)
 }
 
 //--------------------------------------------------------------------------
-// SetBkgRange
+// SetBkg
 //--------------------------------------------------------------------------
 /**
- * <p>set the background values for all the histos.
+ * \brief Sets explicit background values for all data sets.
  *
- * \param bkg vector
+ * Provides pre-calculated background values (one per data set) instead of
+ * calculating them from a background range. This allows different background
+ * values for each histogram.
+ *
+ * \param bkg Vector of background values (should match number of data sets)
  */
 void PPrepFourier::SetBkg(PDoubleVector bkg)
 {
@@ -133,9 +156,13 @@ void PPrepFourier::SetBkg(PDoubleVector bkg)
 // SetPacking
 //--------------------------------------------------------------------------
 /**
- * <p>set the packing for the histograms.
+ * \brief Sets the rebinning/packing factor for data reduction.
  *
- * \param packing number to be used.
+ * Specifies how many adjacent bins to combine during DoPacking(). A value
+ * of 1 means no rebinning, 2 combines pairs of bins, etc. Invalid values
+ * (≤0) are rejected with a warning.
+ *
+ * \param packing Number of bins to combine (must be > 0)
  */
 void PPrepFourier::SetPacking(const Int_t packing)
 {
@@ -150,10 +177,13 @@ void PPrepFourier::SetPacking(const Int_t packing)
 // AddData
 //--------------------------------------------------------------------------
 /**
- * <p>add a data-set (time domain data + meta information) to the internal
+ * \brief Adds a time-domain data set to the internal collection.
- * data vector.
  *
- * \param data set to be added
+ * Stores the raw data and metadata for later processing. Multiple data sets
+ * can be added and will be processed together by DoBkgCorrection(), DoPacking(),
+ * and DoLifeTimeCorrection().
+ *
+ * \param data musrFT_data structure containing raw histogram data and metadata
  */
 void PPrepFourier::AddData(musrFT_data &data)
 {
@@ -164,7 +194,17 @@ void PPrepFourier::AddData(musrFT_data &data)
 // DoBkgCorrection
 //--------------------------------------------------------------------------
 /**
- * <p>Correct the internal data sets according to a background interval given.
+ * \brief Applies background correction to all data sets.
+ *
+ * Subtracts background from each data point. The background can be specified
+ * in two ways:
+ * 1. Background range: Calculates average over the specified bin range
+ * 2. Explicit values: Uses the background values set via SetBkg()
+ *
+ * If fData is not yet initialized, calls InitData() first. If neither
+ * background range nor explicit values are provided, no correction is applied.
+ * Validates that background range is within data bounds and that the number
+ * of explicit background values matches the number of data sets.
  */
 void PPrepFourier::DoBkgCorrection()
 {
@@ -221,7 +261,14 @@ void PPrepFourier::DoBkgCorrection()
 // DoPacking
 //--------------------------------------------------------------------------
 /**
- * <p>Rebin (pack) the internal data.
+ * \brief Applies rebinning/packing to reduce the number of data points.
+ *
+ * Combines adjacent bins according to the packing factor to improve statistics
+ * and reduce data size. Bins are summed in groups of fPacking size. If
+ * fPacking=1, no rebinning is performed.
+ *
+ * If fData is not yet initialized, calls InitData() first. The time resolution
+ * should be adjusted accordingly (multiplied by fPacking) when creating histograms.
  */
 void PPrepFourier::DoPacking()
 {
@@ -256,11 +303,21 @@ void PPrepFourier::DoPacking()
 // DoLifeTimeCorrection
 //--------------------------------------------------------------------------
 /**
- * <p>Try to do a muon life time correction. The idea is to estimate N0 without
+ * \brief Applies muon lifetime correction for theory-free Fourier analysis.
- * any theory. This will be OK for high fields (> couple kGauss) but not so good
- * for low fields.
  *
- * \param fudge rescaling factor for the estimated N0. Should be around 1
+ * Performs a theory-free lifetime correction by:
+ * 1. Multiplying data by exp(t/τ_μ) to remove muon decay
+ * 2. Estimating N0 as the average of the corrected data
+ * 3. Subtracting N0 and normalizing by N0 to get asymmetry-like data
+ *
+ * This approach works well for high fields (>few kGauss) where depolarization
+ * is minimal, but may be less accurate for low fields where significant
+ * relaxation occurs during the muon lifetime.
+ *
+ * If fData is not yet initialized, calls InitData() first. Background correction
+ * should typically be applied before lifetime correction.
+ *
+ * \param fudge Rescaling factor for estimated N0 (typically ~1.0, allows fine-tuning)
  */
 void PPrepFourier::DoLifeTimeCorrection(Double_t fudge)
 {
@@ -299,9 +356,10 @@ void PPrepFourier::DoLifeTimeCorrection(Double_t fudge)
 // GetInfo
 //--------------------------------------------------------------------------
 /**
- * <p>Returns the meta information of a data set.
+ * \brief Returns the metadata string for a specific data set.
  *
- * \param idx index of the object
+ * \param idx Data set index
+ * \return Metadata string from musrFT_data.info, or empty string if idx out of range
  */
 TString PPrepFourier::GetInfo(const UInt_t idx)
 {
@@ -317,9 +375,13 @@ TString PPrepFourier::GetInfo(const UInt_t idx)
 // GetDataSetTag
 //--------------------------------------------------------------------------
 /**
- * <p>Returns the data set tag of the object
+ * \brief Returns the data set tag identifier.
  *
- * \param idx index of the object
+ * The data set tag is used to label and group related data sets, particularly
+ * for average-per-data-set operations in Fourier analysis.
+ *
+ * \param idx Data set index
+ * \return Data set tag value, or -1 if idx out of range
  */
 Int_t PPrepFourier::GetDataSetTag(const UInt_t idx)
 {
@@ -335,8 +397,16 @@ Int_t PPrepFourier::GetDataSetTag(const UInt_t idx)
 // GetData
 //--------------------------------------------------------------------------
 /**
- * <p>Creates the requested TH1F objects and returns them. The ownership is with
+ * \brief Creates ROOT histograms for all processed data sets.
- * the caller.
+ *
+ * Converts the processed data into TH1F histograms with proper time binning.
+ * The time range, bin width, and histogram titles are taken from the
+ * musrFT_data metadata. The packing factor is applied to the time resolution.
+ *
+ * \return Vector of TH1F pointers (caller owns and must delete)
+ *
+ * \note The caller is responsible for deleting the returned histograms.
+ * \note Returns empty vector if no data is present.
  */
 std::vector<TH1F*> PPrepFourier::GetData()
 {
@@ -402,10 +472,18 @@ std::vector<TH1F*> PPrepFourier::GetData()
 // GetData
 //--------------------------------------------------------------------------
 /**
- * <p>Creates the requested TH1F object and returns it. The ownership is with
+ * \brief Creates a ROOT histogram for a specific processed data set.
- * the caller.
  *
- * \param idx index of the requested histogram
+ * Converts a single processed data set into a TH1F histogram with proper
+ * time binning. The time range, bin width, and histogram title are taken
+ * from the musrFT_data metadata. The packing factor is applied to the
+ * time resolution.
+ *
+ * \param idx Data set index
+ * \return TH1F pointer (caller owns and must delete), or nullptr if idx out of range
+ *
+ * \note The caller is responsible for deleting the returned histogram.
+ * \note Returns nullptr if no data is present or idx is out of range.
  */
 TH1F *PPrepFourier::GetData(const UInt_t idx)
 {
@@ -458,7 +536,14 @@ TH1F *PPrepFourier::GetData(const UInt_t idx)
 // InitData (private)
 //--------------------------------------------------------------------------
 /**
- * <p>Copy raw-data to internal data from t0 to the size of raw-data.
+ * \brief Initializes processed data by copying from raw data starting at t0.
+ *
+ * Creates the fData vectors from fRawData, starting from the t0 bin for each
+ * data set. This effectively removes pre-t0 bins and creates a working copy
+ * for subsequent processing (background correction, packing, lifetime correction).
+ *
+ * If t0 is negative or not set, data is copied from bin 0. This method is
+ * called automatically by processing methods if fData is not yet initialized.
  */
 void PPrepFourier::InitData()
 {

src/include/PPrepFourier.h

@@ -40,50 +40,168 @@
 
 //----------------------------------------------------------------------------
 /**
- * <p>Data structure holding raw time domain uSR data together with some
+ * \brief Data structure holding raw time-domain μSR data with metadata.
- * necessary meta information.
+ *
+ * This structure packages raw histogram data together with essential metadata
+ * needed for Fourier transform preparation. It includes timing information,
+ * t0 calibration, and time range specifications for selective data processing.
+ *
+ * \see PPrepFourier for the class that processes this data
  */
 struct musrFT_data {
-  Int_t dataSetTag;        ///< tag to label the data set. Needed for average-per-data-set
+  Int_t dataSetTag;        ///< Data set identifier tag (needed for average-per-data-set operations)
-  TString info;            ///< keeps all the meta information
+  TString info;            ///< Metadata string (run name, histogram info, etc.)
-  Double_t timeResolution; ///< time resolution in (usec)
+  Double_t timeResolution; ///< Time resolution in microseconds (μs)
-  Int_t t0;                ///< keep the t0 bin
+  Int_t t0;                ///< Time zero bin number (start of valid data)
-  Double_t timeRange[2];   ///< time range to be used, given in (usec).
+  Double_t timeRange[2];   ///< Time range to process: [0]=start, [1]=end in microseconds (μs)
-  PDoubleVector rawData;   ///< a single time domain data vector
+  PDoubleVector rawData;   ///< Raw time-domain data vector (bin counts)
 };
 
 //----------------------------------------------------------------------------
 /**
- * <p>Little helper class to prepare time-domain data for Fourier transform, without
+ * \brief Prepares time-domain μSR data for Fourier transformation.
- * theory, etc.
+ *
+ * PPrepFourier is a utility class that processes raw time-domain μSR data
+ * before Fourier transformation. It performs essential preprocessing steps:
+ * - Background correction (using range or explicit values)
+ * - Data rebinning/packing for improved statistics
+ * - Muon lifetime correction for theory-free analysis
+ * - Time range selection
+ *
+ * The class handles multiple data sets simultaneously and prepares them
+ * for subsequent Fourier analysis without requiring theoretical fit functions.
+ *
+ * \par Usage Example:
+ * \code
+ * PPrepFourier prep(packing, bkgRange, bkgValues);
+ * prep.AddData(dataSet1);
+ * prep.AddData(dataSet2);
+ * prep.DoBkgCorrection();
+ * prep.DoPacking();
+ * prep.DoLifeTimeCorrection(1.0);
+ * std::vector<TH1F*> histos = prep.GetData();
+ * \endcode
+ *
+ * \see musrFT_data for the input data structure
  */
 class PPrepFourier {
   public:
+    /// Default constructor (requires separate configuration)
     PPrepFourier();
+
+    /**
+     * \brief Full constructor with all configuration parameters.
+     * \param packing Rebinning factor (1=no rebinning, 2=combine 2 bins, etc.)
+     * \param bkgRange Background range [start, end] in bins (-1 if not used)
+     * \param bkg Vector of explicit background values (one per data set)
+     */
     PPrepFourier(const Int_t packing, const Int_t *bkgRange, PDoubleVector bkg);
+
+    /// Destructor
     virtual ~PPrepFourier();
 
+    /**
+     * \brief Sets background range for automatic background calculation.
+     * \param bkgRange Array [start, end] specifying background bins (both ≥-1)
+     */
     virtual void SetBkgRange(const Int_t *bkgRange);
+
+    /**
+     * \brief Sets explicit background values for each data set.
+     * \param bkg Vector of background values (one per histogram)
+     */
     virtual void SetBkg(PDoubleVector bkg);
+
+    /**
+     * \brief Sets rebinning/packing factor for data reduction.
+     * \param packing Number of bins to combine (must be > 0)
+     */
     virtual void SetPacking(const Int_t packing);
+
+    /**
+     * \brief Adds a time-domain data set for processing.
+     * \param data musrFT_data structure containing raw data and metadata
+     */
     virtual void AddData(musrFT_data &data);
+
+    /**
+     * \brief Applies background correction to all data sets.
+     *
+     * Uses either the background range (averaged over range) or explicit
+     * background values. Background is subtracted from all data points.
+     */
     virtual void DoBkgCorrection();
+
+    /**
+     * \brief Applies rebinning/packing to reduce data points.
+     *
+     * Combines adjacent bins according to the packing factor to improve
+     * statistics and reduce the number of data points.
+     */
     virtual void DoPacking();
+
+    /**
+     * \brief Applies muon lifetime correction for theory-free analysis.
+     * \param fudge Rescaling factor for estimated N0 (typically ~1.0)
+     *
+     * Multiplies data by exp(t/τ) to remove muon decay, estimates N0 from
+     * the average, and normalizes to create asymmetry-like data. Works best
+     * for high fields (>few kGauss) where depolarization is minimal.
+     */
     virtual void DoLifeTimeCorrection(Double_t fudge);
 
+    /**
+     * \brief Returns metadata string for a specific data set.
+     * \param idx Data set index
+     * \return Metadata string, or empty string if idx out of range
+     */
     TString GetInfo(const UInt_t idx);
+
+    /**
+     * \brief Returns data set tag identifier.
+     * \param idx Data set index
+     * \return Data set tag, or -1 if idx out of range
+     */
     Int_t GetDataSetTag(const UInt_t idx);
+
+    /**
+     * \brief Returns number of stored data sets.
+     * \return Number of data sets added via AddData()
+     */
     UInt_t GetNoOfData() { return fRawData.size(); }
+
+    /**
+     * \brief Creates ROOT histograms for all processed data sets.
+     * \return Vector of TH1F pointers (caller owns the histograms)
+     *
+     * Creates histograms with proper time binning, respecting time ranges
+     * and packing. The caller is responsible for deleting the histograms.
+     */
     std::vector<TH1F*> GetData();
+
+    /**
+     * \brief Creates ROOT histogram for a specific processed data set.
+     * \param idx Data set index
+     * \return TH1F pointer (caller owns), or nullptr if idx out of range
+     *
+     * Creates a histogram with proper time binning for the specified data set.
+     * The caller is responsible for deleting the histogram.
+     */
     TH1F *GetData(const UInt_t idx);
 
   private:
-    std::vector<musrFT_data> fRawData;
+    std::vector<musrFT_data> fRawData;  ///< Raw input data sets with metadata
-    std::vector<PDoubleVector>fData;
+    std::vector<PDoubleVector> fData;   ///< Processed data (after t0, corrections, packing)
-    Int_t fBkgRange[2];
+    Int_t fBkgRange[2];                 ///< Background range: [0]=start bin, [1]=end bin (-1=unused)
-    PDoubleVector fBkg;
+    PDoubleVector fBkg;                 ///< Explicit background values (one per data set)
-    Int_t fPacking;
+    Int_t fPacking;                     ///< Rebinning factor (1=no rebinning, N=combine N bins)
 
+    /**
+     * \brief Initializes processed data from raw data.
+     *
+     * Copies raw data to fData starting from t0 bin. This is called
+     * automatically by processing methods if needed.
+     */
     virtual void InitData();
 };