improve the doxygen docu of mupp.* Pmupp.* (musredit_qt6).

src/musredit_qt6/mupp/Pmupp.cpp

@@ -27,6 +27,27 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file Pmupp.cpp
+ *
+ * @brief Implementation of core data classes for mupp parameter management.
+ *
+ * This file implements the data structures and handler classes for managing
+ * muSR fit parameters in mupp. It provides the functionality to read, parse,
+ * and access parameter data from various file formats (db, dat, msr).
+ *
+ * Key implementations:
+ * - PmuppParam: Storage and access for individual parameters
+ * - PmuppRun: Container for all parameters from a single run
+ * - PmuppCollection: Container for multiple related runs
+ * - PParamDataHandler: File I/O and data management operations
+ *
+ * The file parsers handle three main formats:
+ * - DB format: Structured database format with metadata and parameters
+ * - DAT/TXT format: Column-based format with flexible error handling
+ * - MSR format: Indirect support via msr2data external tool
+ */
+
 #include <iostream>
 #include <cmath>
 
@@ -55,7 +76,9 @@
 
 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
- * @brief PmuppParam::PmuppParam. Ctor
+ * @brief Default constructor for PmuppParam.
+ *
+ * Initializes a parameter with undefined values (MUPP_UNDEF) and an empty name.
  */
 PmuppParam::PmuppParam() {
   ResetParam();
@@ -63,10 +86,14 @@ PmuppParam::PmuppParam() {
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppParam::PmuppParam. Ctor
+ * @brief Constructor for PmuppParam with symmetric errors.
- * @param name parameter name
+ *
- * @param param parameter value
+ * Initializes a parameter with a name, value, and symmetric error
- * @param posErr parameter error
+ * (positive error = negative error).
+ *
+ * @param name parameter name (e.g., "alpha", "lambda")
+ * @param param parameter central value
+ * @param posErr parameter error (used for both positive and negative)
  */
 PmuppParam::PmuppParam(QString name, double param, double posErr)
 {
@@ -75,11 +102,16 @@ PmuppParam::PmuppParam(QString name, double param, double posErr)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppParam::PmuppParam. Ctor
+ * @brief Constructor for PmuppParam with asymmetric errors.
- * @param name parameter name
+ *
- * @param param parameter value
+ * Initializes a parameter with a name, value, and asymmetric errors.
- * @param posErr positive parameter error
+ * This is useful when the uncertainty is not symmetric around the
- * @param negErr negative parameter error
+ * central value, which can occur with non-Gaussian likelihoods.
+ *
+ * @param name parameter name (e.g., "alpha", "lambda")
+ * @param param parameter central value
+ * @param posErr positive (upper) parameter error
+ * @param negErr negative (lower) parameter error
  */
 PmuppParam::PmuppParam(QString name, double param, double posErr, double negErr)
 {
@@ -88,7 +120,10 @@ PmuppParam::PmuppParam(QString name, double param, double posErr, double negErr)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppParam::ResetParam. Reset the parameter values
+ * @brief Resets the parameter to undefined state.
+ *
+ * Clears the parameter name and sets all numeric values to MUPP_UNDEF,
+ * effectively marking the parameter as uninitialized.
  */
 void PmuppParam::ResetParam()
 {
@@ -100,9 +135,13 @@ void PmuppParam::ResetParam()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppParam::SetParam. Set a parameter
+ * @brief Sets parameter with symmetric errors.
+ *
+ * Sets the parameter name, value, and error. The negative error is not
+ * explicitly set and should be set separately if asymmetric errors are needed.
+ *
  * @param name parameter name
- * @param param parameter value
+ * @param param parameter central value
  * @param posErr parameter error
  */
 void PmuppParam::SetParam(QString name, double param, double posErr)
@@ -114,11 +153,15 @@ void PmuppParam::SetParam(QString name, double param, double posErr)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppParam::SetParam. Set a parameter
+ * @brief Sets parameter with asymmetric errors.
+ *
+ * Sets the parameter name, value, positive error, and negative error.
+ * Use this when the uncertainty is asymmetric around the central value.
+ *
  * @param name parameter name
- * @param param parameter value
+ * @param param parameter central value
- * @param posErr positive parameter value
+ * @param posErr positive (upper) error value
- * @param negErr negative parameter value
+ * @param negErr negative (lower) error value
  */
 void PmuppParam::SetParam(QString name, double param, double posErr, double negErr)
 {
@@ -130,9 +173,13 @@ void PmuppParam::SetParam(QString name, double param, double posErr, double negE
 
 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
- * @brief PmuppRun::GetParam. Get a parameter from a run
+ * @brief Retrieves a parameter from a run by index.
- * @param idx index of the parameter
+ *
- * @return the parameter value
+ * Returns a copy of the parameter at the specified index. If the index
+ * is out of range, returns an empty (default-constructed) parameter.
+ *
+ * @param idx zero-based index of the parameter to retrieve
+ * @return the parameter at the specified index, or an empty parameter if out of range
  */
 PmuppParam PmuppRun::GetParam(unsigned int idx)
 {
@@ -146,9 +193,13 @@ PmuppParam PmuppRun::GetParam(unsigned int idx)
 
 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
- * @brief PmuppCollection::GetRun. Returns a run from a collection.
+ * @brief Retrieves a run from a collection by index.
- * @param idx of the run in a collection
+ *
- * @return a run from a collection
+ * Returns a copy of the run at the specified index. If the index
+ * is out of range, returns an empty (default-constructed) run.
+ *
+ * @param idx zero-based index of the run to retrieve
+ * @return the run at the specified index, or an empty run if out of range
  */
 PmuppRun PmuppCollection::GetRun(unsigned int idx)
 {
@@ -162,9 +213,12 @@ PmuppRun PmuppCollection::GetRun(unsigned int idx)
 
 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
- * @brief PParamDataHandler::NewCollection. Adds an empty new collection with
+ * @brief Creates and adds an empty collection with the specified name.
- * name 'name'.
+ *
- * @param name of the new collection
+ * This method creates a new empty collection and adds it to the handler's
+ * collection vector. The collection can then be populated with runs later.
+ *
+ * @param name the name to assign to the new collection
  */
 void PParamDataHandler::NewCollection(const QString name)
 {
@@ -176,17 +230,24 @@ void PParamDataHandler::NewCollection(const QString name)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::analyzeFileList. In case the input is given by
+ * @brief Analyzes a list of msr-files to prepare arguments for msr2data.
- * msr-files, the structure of the file names needs to be analyzed that
- * msr2data can be called.
  *
- * @param fln list of msr-files to be analyzed.
+ * When parameter data is provided as msr-files (muSR fit input files),
- * @param collectionName output collection name (db-/dat-file).
+ * this function analyzes their structure to extract run numbers and
- * @param arg argument list which is needed to feed msr2data
+ * extensions, preparing the argument list needed to invoke the msr2data
- * @param workDir working directory
+ * external tool for conversion to db format.
- * @param errorMsg error message in case something went wrong.
  *
- * @return true if successful, false otherwise
+ * The function expects msr-files with names following the pattern:
+ * <runNumber><extension>.msr where <extension> starts with '_'.
+ * All msr-files in the list must have the same extension.
+ *
+ * @param fln list of msr-file paths to be analyzed
+ * @param collectionName output parameter: name for the resulting db/dat collection file
+ * @param arg output parameter: argument list to be passed to msr2data
+ * @param workDir output parameter: working directory where files are located
+ * @param errorMsg output parameter: error message if analysis fails
+ *
+ * @return true if analysis is successful, false otherwise
  */
 bool PParamDataHandler::analyzeFileList(const QStringList &fln, QString &collectionName,
                                         QStringList &arg, QString &workDir, QString &errorMsg)
@@ -260,11 +321,27 @@ bool PParamDataHandler::analyzeFileList(const QStringList &fln, QString &collect
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::ReadParamFile. Reads a msr-file.
+ * @brief Reads parameter file(s) and loads them into collections.
- * @param fln file name of the msr-file to be read
- * @param errorMsg error message in case reading fails.
  *
- * @return true on success, otherwise false.
+ * This is the main entry point for loading parameter data. It handles
+ * multiple file formats (msr, db, dat) and dispatches to the appropriate
+ * reader function. For msr-files, it invokes msr2data to convert them to
+ * db format first.
+ *
+ * File format handling:
+ * - .msr files: Converted via msr2data, then loaded as db
+ * - .db files: Loaded directly via ReadDbFile()
+ * - .dat/.txt files: Loaded directly via ReadColumnParamFile()
+ *
+ * Multiple files can be loaded in a single call. Each file becomes a
+ * separate collection in the handler.
+ *
+ * @param fln list of file names (with paths) to be loaded
+ * @param errorMsg output parameter: error message if reading fails
+ *
+ * @return true on success, false on any error
+ *
+ * @see ReadDbFile(), ReadColumnParamFile(), analyzeFileList()
  */
 bool PParamDataHandler::ReadParamFile(const QStringList fln, QString &errorMsg)
 {
@@ -397,12 +474,27 @@ bool PParamDataHandler::ReadParamFile(const QStringList fln, QString &errorMsg)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::ReadDbFile. Reads a db-file.
+ * @brief Reads and parses a db-format parameter file.
- * @param fln file name of the db-file
- * @param valid true on success, otherwise false
- * @param errorMsg error messages in case read fails
  *
- * @return the collection object containing the db-file on success.
+ * The db format is a structured text format containing parameter data with
+ * metadata sections. The file structure includes:
+ * - Title and abstract sections (ignored by this parser)
+ * - Data-tags section (ignored)
+ * - Parameter entries section (following "\\-e" marker)
+ * - Each parameter: name=value, posError, negError, unused
+ * - Run entries: runNumber, title
+ *
+ * The function validates that all runs have the same number of parameters
+ * to ensure data consistency.
+ *
+ * @param fln path to the db-file to be read
+ * @param valid output parameter: set to true on success, false on failure
+ * @param errorMsg output parameter: error message describing any failures
+ *
+ * @return a PmuppCollection object containing all runs and parameters from the file.
+ *         Returns an empty collection if reading fails (valid will be false).
+ *
+ * @see ReadParamFile(), ReadColumnParamFile()
  */
 PmuppCollection PParamDataHandler::ReadDbFile(const QString fln, bool &valid, QString &errorMsg)
 {
@@ -554,12 +646,31 @@ PmuppCollection PParamDataHandler::ReadDbFile(const QString fln, bool &valid, QS
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::ReadColumnParamFile. Reads a dat-file
+ * @brief Reads and parses a column-based parameter file (dat/txt format).
- * @param fln file name of the dat-file to be read
- * @param valid true on success, false otherwise.
- * @param errorMsg error message in case read fails.
  *
- * @return the collection object containing the dat-file on success.
+ * The column format is a simple text format where:
+ * - First line: Header with column names
+ * - Following lines: Data values (one row per run)
+ * - Columns are whitespace-separated
+ *
+ * Column naming conventions:
+ * - Parameter names without suffix: parameter values
+ * - Names ending with "Err": symmetric errors
+ * - Names ending with "PosErr": positive (upper) errors
+ * - Names ending with "NegErr": negative (lower) errors
+ * - Column named "RUN": run number identifier
+ *
+ * Error handling supports both symmetric (single error column) and
+ * asymmetric (separate PosErr/NegErr columns) error specifications.
+ *
+ * @param fln path to the dat/txt-file to be read
+ * @param valid output parameter: set to true on success, false on failure
+ * @param errorMsg output parameter: error message describing any failures
+ *
+ * @return a PmuppCollection object containing all runs and parameters from the file.
+ *         Returns an empty collection if reading fails (valid will be false).
+ *
+ * @see ReadParamFile(), ReadDbFile()
  */
 PmuppCollection PParamDataHandler::ReadColumnParamFile(const QString fln, bool &valid, QString &errorMsg)
 {
@@ -691,12 +802,18 @@ PmuppCollection PParamDataHandler::ReadColumnParamFile(const QString fln, bool &
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::GetCollection. Get a single collection from all
+ * @brief Retrieves a collection by index (by value).
- * the loaded collections
- * @param idx of the collection
- * @param valid true if collection is found
  *
- * @return requested collection on success.
+ * Returns a copy of the collection at the specified index position.
+ * If the index is out of range, returns an empty collection and sets
+ * valid to false.
+ *
+ * @param idx zero-based index of the collection to retrieve
+ * @param valid output parameter: set to true if collection found, false otherwise
+ *
+ * @return copy of the requested collection, or an empty collection if not found
+ *
+ * @see GetCollection(const QString, bool&), GetCollection(const int)
  */
 PmuppCollection PParamDataHandler::GetCollection(const int idx, bool &valid)
 {
@@ -821,13 +938,23 @@ QString PParamDataHandler::GetCollectionName(const int idx)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::GetValues. Get the data values of a parameter of
+ * @brief Retrieves all values for a specific parameter across all runs.
- * a requested collection.
- * @param collName name of the collection
- * @param paramName parameter name
  *
- * @return data values of the requested parameter name of the collection collName.
+ * This method extracts the central values of a named parameter from all
- *         Empty data vector otherwise.
+ * runs in the specified collection. The returned vector has one entry per
+ * run, in the order they appear in the collection.
+ *
+ * This is useful for plotting parameter evolution (e.g., relaxation rate
+ * vs. temperature) where each run represents a different experimental
+ * condition.
+ *
+ * @param collName name of the collection to query
+ * @param paramName name of the parameter to extract (e.g., "alpha", "lambda")
+ *
+ * @return vector of parameter values, one per run in the collection.
+ *         Returns an empty vector if the collection or parameter is not found.
+ *
+ * @see GetPosErr(), GetNegErr()
  */
 QVector<double> PParamDataHandler::GetValues(QString collName, QString paramName)
 {
@@ -867,13 +994,21 @@ QVector<double> PParamDataHandler::GetValues(QString collName, QString paramName
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::GetPosErr. Get the positive data error values of
+ * @brief Retrieves all positive errors for a specific parameter across all runs.
- * a parameter of a requested collection.
- * @param collName name of the requested collection
- * @param paramName parameter name
  *
- * @return positive error values of the requested parameter name of the
+ * This method extracts the positive (upper) error values of a named parameter
- *         collection collName. Empty positive error vector otherwise.
+ * from all runs in the specified collection. The returned vector has one entry
+ * per run, in the order they appear in the collection.
+ *
+ * Used in conjunction with GetValues() for plotting parameters with error bars.
+ *
+ * @param collName name of the collection to query
+ * @param paramName name of the parameter whose positive errors to extract
+ *
+ * @return vector of positive error values, one per run in the collection.
+ *         Returns an empty vector if the collection or parameter is not found.
+ *
+ * @see GetValues(), GetNegErr()
  */
 QVector<double> PParamDataHandler::GetPosErr(QString collName, QString paramName)
 {
@@ -913,13 +1048,22 @@ QVector<double> PParamDataHandler::GetPosErr(QString collName, QString paramName
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::GetNegErr. Get the negative data error values of
+ * @brief Retrieves all negative errors for a specific parameter across all runs.
- * a parameter of a requested collection.
- * @param collName name of the requested collection
- * @param paramName parameter name
  *
- * @return negative error values of the requested parameter name of the
+ * This method extracts the negative (lower) error values of a named parameter
- *         collection collName. Empty negative error vector otherwise.
+ * from all runs in the specified collection. The returned vector has one entry
+ * per run, in the order they appear in the collection.
+ *
+ * Used in conjunction with GetValues() and GetPosErr() for plotting parameters
+ * with asymmetric error bars.
+ *
+ * @param collName name of the collection to query
+ * @param paramName name of the parameter whose negative errors to extract
+ *
+ * @return vector of negative error values, one per run in the collection.
+ *         Returns an empty vector if the collection or parameter is not found.
+ *
+ * @see GetValues(), GetPosErr()
  */
 QVector<double> PParamDataHandler::GetNegErr(QString collName, QString paramName)
 {
@@ -959,9 +1103,13 @@ QVector<double> PParamDataHandler::GetNegErr(QString collName, QString paramName
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::RemoveCollection. Remove a collection from the
+ * @brief Removes a collection from the handler by name.
- * data handler.
+ *
- * @param name of the collection to be removed.
+ * Searches for a collection with the specified name and removes it from
+ * the internal collection vector. If multiple collections have the same
+ * name, only the first match is removed.
+ *
+ * @param name the name of the collection to be removed
  */
 void PParamDataHandler::RemoveCollection(QString name)
 {
@@ -975,10 +1123,13 @@ void PParamDataHandler::RemoveCollection(QString name)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::ReplaceCollection. Replaces a collection at index
+ * @brief Replaces a collection at the specified index.
- * position idx.
+ *
- * @param coll collection
+ * Replaces an existing collection with a new one at the given index position.
- * @param idx index of the collection to be replaced
+ * If the index is out of range, no action is taken.
+ *
+ * @param coll the new collection to insert
+ * @param idx the index position where the collection should be replaced
  */
 void PParamDataHandler::ReplaceCollection(PmuppCollection coll, int idx)
 {
@@ -990,7 +1141,17 @@ void PParamDataHandler::ReplaceCollection(PmuppCollection coll, int idx)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::Dump. Dumps the collection onto stdout
+ * @brief Dumps all collection data to stdout for debugging.
+ *
+ * Prints a formatted representation of all loaded collections, including
+ * collection names, run numbers, run names, and all parameters with their
+ * values and errors. This is primarily used for debugging and verification
+ * purposes.
+ *
+ * Output format shows:
+ * - Collection separator and name
+ * - For each run: run number, run name
+ * - For each parameter: name, value, negative error, positive error
  */
 void PParamDataHandler::Dump()
 {
@@ -1017,7 +1178,11 @@ void PParamDataHandler::Dump()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::readFromStdOut
+ * @brief Slot to handle standard output from msr2data process.
+ *
+ * This slot is connected to the readyReadStandardOutput signal of the
+ * QProcess used to run msr2data. It reads and logs all output from the
+ * process's stdout.
  */
 void PParamDataHandler::readFromStdOut()
 {
@@ -1026,7 +1191,11 @@ void PParamDataHandler::readFromStdOut()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::readFromStdErr
+ * @brief Slot to handle standard error from msr2data process.
+ *
+ * This slot is connected to the readyReadStandardError signal of the
+ * QProcess used to run msr2data. It reads and logs all output from the
+ * process's stderr.
  */
 void PParamDataHandler::readFromStdErr()
 {
@@ -1035,9 +1204,14 @@ void PParamDataHandler::readFromStdErr()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PParamDataHandler::processDone
+ * @brief Slot to handle completion of msr2data process.
- * @param exitCode
+ *
- * @param exitStatus
+ * This slot is connected to the finished signal of the QProcess used to
+ * run msr2data. It checks the exit status and logs errors if the process
+ * crashed or exited with a non-zero exit code.
+ *
+ * @param exitCode the exit code returned by the process
+ * @param exitStatus indicates whether the process exited normally or crashed
  */
 void PParamDataHandler::processDone(int exitCode, QProcess::ExitStatus exitStatus)
 {

src/musredit_qt6/mupp/Pmupp.h

@@ -27,6 +27,23 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file Pmupp.h
+ *
+ * @brief Core data structures and handler classes for mupp parameter management.
+ *
+ * This header file defines the fundamental data structures used in mupp for
+ * managing muSR fit parameters. It implements a hierarchical data model:
+ * - PmuppParam: Individual parameter with value and errors
+ * - PmuppRun: Collection of parameters from a single run
+ * - PmuppCollection: Set of runs forming a complete dataset
+ * - PParamDataHandler: Manager class for loading and accessing collections
+ *
+ * The classes support reading parameter data from multiple file formats
+ * (db, dat, msr) and provide interfaces for accessing parameter values,
+ * errors, and metadata.
+ */
+
 #ifndef _PMUPP_H_
 #define _PMUPP_H_
 
@@ -38,12 +55,27 @@
 #include <QStringList>
 #include <QProcess>
 
+/**
+ * @brief Undefined value constant used to indicate missing or invalid data.
+ *
+ * This constant is used throughout mupp to mark parameters or values that
+ * have not been set or are invalid. It is set to a very large number that
+ * is unlikely to occur in real experimental data.
+ */
 #define MUPP_UNDEF 1.0e99
 
 //----------------------------------------------------------------------------
 /**
- * <p>The PmuppParam class. It handles a single parameter: name, value,
+ * @brief Represents a single fit parameter with its value and uncertainties.
- * positive- and negative error.
+ *
+ * The PmuppParam class encapsulates a single parameter from a muSR fit,
+ * including its name, central value, and asymmetric error bars (positive
+ * and negative errors). This class is the fundamental building block for
+ * storing parameter information in mupp.
+ *
+ * The class supports both symmetric errors (where positive and negative
+ * errors are equal) and asymmetric errors (where they differ), which is
+ * common in fits with non-Gaussian likelihood profiles.
  */
 class PmuppParam {
   public:
@@ -54,84 +86,238 @@ class PmuppParam {
     void ResetParam();
     void SetParam(QString name, double param, double posErr);
     void SetParam(QString name, double param, double posErr, double negErr);
+
+    /**
+     * @brief Sets the parameter name.
+     * @param name the parameter name to be set
+     */
     void SetName(QString name) { fName = name; }
+
+    /**
+     * @brief Sets the parameter value.
+     * @param dval the parameter value to be set
+     */
     void SetValue(double dval) { fValue = dval; }
+
+    /**
+     * @brief Sets the positive error of the parameter.
+     * @param dval the positive error value to be set
+     */
     void SetPosErr(double dval) { fPosErr = dval; }
+
+    /**
+     * @brief Sets the negative error of the parameter.
+     * @param dval the negative error value to be set
+     */
     void SetNegErr(double dval) { fNegErr = dval; }
 
+    /**
+     * @brief Gets the parameter name.
+     * @return the parameter name
+     */
     QString GetName() { return fName; }
+
+    /**
+     * @brief Gets the parameter value.
+     * @return the parameter value
+     */
     double GetValue() { return fValue; }
+
+    /**
+     * @brief Gets the positive error of the parameter.
+     * @return the positive error value
+     */
     double GetPosErr() { return fPosErr; }
+
+    /**
+     * @brief Gets the negative error of the parameter.
+     * @return the negative error value
+     */
     double GetNegErr() { return fNegErr; }
 
   private:
-    QString fName; ///< parameter name
+    QString fName; ///< parameter name (e.g., "alpha", "lambda", "phase")
-    double fValue; ///< parameter value
+    double fValue; ///< central value of the parameter
-    double fPosErr; ///< positive error of the parameter
+    double fPosErr; ///< positive (upper) error of the parameter
-    double fNegErr; ///< negative error of the parameter
+    double fNegErr; ///< negative (lower) error of the parameter
 };
 
 //----------------------------------------------------------------------------
 /**
- * <p>The PmuppRun class. Contains all the parameters of a single run.
+ * @brief Represents all fit parameters from a single experimental run.
+ *
+ * The PmuppRun class contains a complete set of parameters from one muSR
+ * run, including the run number, run name/title, and a vector of all fit
+ * parameters (PmuppParam objects) associated with that run.
+ *
+ * This class forms the intermediate level in the data hierarchy:
+ * Parameter -> Run -> Collection
  */
 class PmuppRun {
   public:
+    /**
+     * @brief Default constructor. Initializes an empty run with invalid number.
+     */
     PmuppRun() { fNumber = -1; fName=""; fParam.clear(); }
+
+    /**
+     * @brief Destructor. Cleans up the run data.
+     */
     ~PmuppRun() { fNumber = -1; fName=""; fParam.clear(); }
 
+    /**
+     * @brief Clears all run data and resets to initial state.
+     */
     void Clear() { fNumber = -1; fName=""; fParam.clear(); }
+
+    /**
+     * @brief Sets the run name/title.
+     * @param name the run name or title string to be set
+     */
     void SetName(QString name) { fName = name; }
+
+    /**
+     * @brief Sets the run number.
+     * @param ival the run number to be set
+     */
     void SetNumber(int ival) { fNumber = ival; }
+
+    /**
+     * @brief Adds a parameter to this run.
+     * @param param the PmuppParam object to be added to the parameter list
+     */
     void AddParam(PmuppParam param) { fParam.push_back(param); }
 
+    /**
+     * @brief Gets the run number.
+     * @return the run number (may be -1 if not set)
+     */
     int GetNumber() { return fNumber; }
+
+    /**
+     * @brief Gets the run name/title.
+     * @return the run name or title string
+     */
     QString GetName() { return fName; }
+
+    /**
+     * @brief Gets the number of parameters in this run.
+     * @return the count of parameters stored in this run
+     */
     int GetNoOfParam() { return fParam.size(); }
+
     PmuppParam GetParam(unsigned int idx);
 
   private:
-    int fNumber; ///< run number
+    int fNumber; ///< run number identifier
-    QString fName; ///< name of the run
+    QString fName; ///< descriptive name or title of the run
-    QVector<PmuppParam> fParam; ///< parameters of the run
+    QVector<PmuppParam> fParam; ///< vector of all fit parameters for this run
 };
 
 //----------------------------------------------------------------------------
 /**
- * <p>The PmuppCollection class. Is collecting a number of runs. Typically
+ * @brief Represents a collection of related experimental runs.
- * something like a full temperature scan, an energy scan, etc.
+ *
+ * The PmuppCollection class groups together multiple runs that form a
+ * coherent dataset, typically representing a scan over some experimental
+ * parameter such as temperature, magnetic field, energy, pressure, etc.
+ *
+ * A collection corresponds to a single data file (db, dat, or msr format)
+ * and contains all runs from that file. This is the top level in the
+ * data hierarchy: Parameter -> Run -> Collection
+ *
+ * Example use cases:
+ * - Temperature scan: multiple runs at different temperatures
+ * - Field scan: runs at various magnetic field values
+ * - Energy scan: runs at different implantation energies
  */
 class PmuppCollection {
   public:
+    /**
+     * @brief Default constructor. Initializes an empty collection.
+     */
     PmuppCollection() { fPathName=""; fName = ""; fRun.clear(); }
 
+    /**
+     * @brief Sets the full path name of the collection file.
+     * @param pathName the absolute or relative path to the collection file
+     */
     void SetPathName(QString pathName) { fPathName = pathName; }
+
+    /**
+     * @brief Sets the collection name.
+     * @param name the display name for this collection
+     */
     void SetName (QString name) { fName = name; }
+
+    /**
+     * @brief Adds a run to this collection.
+     * @param run the PmuppRun object to be added to the run list
+     */
     void AddRun(PmuppRun run) { fRun.push_back(run); }
 
+    /**
+     * @brief Gets the full path name of the collection file.
+     * @return the path name string
+     */
     QString GetPathName() { return fPathName; }
+
+    /**
+     * @brief Gets the collection name.
+     * @return the collection name string
+     */
     QString GetName() { return fName; }
+
+    /**
+     * @brief Gets the number of runs in this collection.
+     * @return the count of runs stored in this collection
+     */
     int GetNoOfRuns() { return fRun.size(); }
+
     PmuppRun GetRun(unsigned int idx);
 
   private:
-    QString fPathName; ///< path-name of the collection
+    QString fPathName; ///< full path and filename of the collection data file
-    QString fName; ///< name of the collection
+    QString fName; ///< display name of the collection (usually just the filename)
-    QVector<PmuppRun> fRun; ///< all the runs in the collection
+    QVector<PmuppRun> fRun; ///< vector of all runs in this collection
 };
 
 //----------------------------------------------------------------------------
 /**
- * <p>The PParamDataHandler class. This class handles all the collections
+ * @brief Central manager class for loading and accessing parameter collections.
- * loaded.
+ *
+ * The PParamDataHandler class is responsible for managing all loaded parameter
+ * collections in mupp. It provides functionality for:
+ * - Reading and parsing parameter files (db, dat, msr formats)
+ * - Managing multiple collections simultaneously
+ * - Providing access to parameter data by collection and parameter name
+ * - Handling conversion of msr files via msr2data external process
+ *
+ * This class acts as the primary interface between the data storage and the
+ * GUI or scripting components of mupp. It maintains a vector of all loaded
+ * collections and provides various query methods to extract parameter values
+ * and errors.
+ *
+ * File format support:
+ * - .db files: muSR database format with structured parameter entries
+ * - .dat/.txt files: Column-based parameter files
+ * - .msr files: muSR fit input files (converted via msr2data)
  */
 class PParamDataHandler : public QObject {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Default constructor.
+     */
     PParamDataHandler() {}
 
+    /**
+     * @brief Gets the total number of loaded collections.
+     * @return the count of collections currently managed
+     */
     int GetNoOfCollections() { return fCollection.size(); }
+
     void NewCollection(const QString name);
 
     bool ReadParamFile(const QStringList fln, QString &errorMsg);
@@ -155,11 +341,18 @@ class PParamDataHandler : public QObject {
     void Dump();
 
   signals:
+    /**
+     * @brief Signal emitted when new data has been successfully loaded.
+     *
+     * This signal is emitted after parameter files have been read and
+     * collections have been added to the handler. Connected slots can
+     * update their displays or perform other actions in response.
+     */
     void newData();
 
   private:
-    std::unique_ptr<QProcess> fProc; ///< this will be needed if msr2data needs to be called
+    std::unique_ptr<QProcess> fProc; ///< process handle for invoking msr2data when msr files need conversion
-    QVector<PmuppCollection> fCollection; ///< all the collections handeled
+    QVector<PmuppCollection> fCollection; ///< vector containing all loaded collections
 
     bool analyzeFileList(const QStringList &fln, QString &collectionName,
                          QStringList &arg, QString &workDir, QString &errorMsg);

src/musredit_qt6/mupp/mupp.cpp

@@ -27,6 +27,25 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file mupp.cpp
+ *
+ * @brief Implementation of mupp (muon parameter plotter) main application.
+ *
+ * mupp is a tool for plotting muon spin spectroscopy (muSR) fit parameters
+ * as a function of various experimental conditions (temperature, field, etc.).
+ * The application supports both GUI and script-based modes. It can handle
+ * parameter files in db, dat, and msr formats, allowing users to visualize
+ * trends in fit parameters across multiple runs.
+ *
+ * The main functionality includes:
+ * - Loading and parsing parameter files (db, dat, msr)
+ * - Interactive GUI for data selection and visualization
+ * - Script-based batch processing for automated plotting
+ * - Export of plots in various formats (pdf, png, svg, etc.)
+ * - Generation of ROOT macros for further analysis
+ */
+
 #include <iostream>
 
 #include <QObject>
@@ -49,7 +68,14 @@
 
 //------------------------------------------------------------------------
 /**
- * <p>mupp script help.
+ * @brief Displays the mupp script syntax help to stdout.
+ *
+ * This function prints detailed information about the mupp script commands,
+ * including available commands, their syntax, and descriptions. The script
+ * commands allow for batch processing and automated plotting of parameter
+ * data without user interaction.
+ *
+ * @see mupp_syntax(), mupp_script_read(), mupp_script_syntax_check()
  */
 void mupp_script_syntax()
 {
@@ -89,7 +115,18 @@ void mupp_script_syntax()
 
 //------------------------------------------------------------------------
 /**
- * <p>mupp syntax help.
+ * @brief Displays the mupp application syntax and usage help to stdout.
+ *
+ * This function prints the complete usage information for the mupp application,
+ * including command-line options, file path specifications, and supported file
+ * formats. It also calls mupp_script_syntax() to display script-specific help.
+ *
+ * Command-line options include:
+ * - Help and version information
+ * - Script mode execution
+ * - File path and file name specifications
+ *
+ * @see mupp_script_syntax()
  */
 void mupp_syntax()
 {
@@ -108,12 +145,21 @@ void mupp_syntax()
 
 //------------------------------------------------------------------------
 /**
- * <p>Reads a mupp script and feeds its content to list.
+ * @brief Reads a mupp script file and parses its content into a string list.
  *
- * @param fln mupp script file name
+ * This function reads a mupp script file line by line, processes each line by:
- * @param list content of the mupp script
+ * - Removing leading and trailing whitespace
+ * - Skipping empty lines
+ * - Skipping comment lines (starting with '#', '%', or '//')
+ * - Removing trailing comments from command lines
+ * - Adding valid command lines to the output list
  *
- * @return 0 if success, otherwise -1
+ * @param fln the mupp script file name (path) to be read
+ * @param list reference to QStringList that will contain the parsed script commands
+ *
+ * @return 0 on success, -1 if the file cannot be opened
+ *
+ * @see mupp_script_syntax_check(), mupp_script_syntax()
  */
 int mupp_script_read(const char *fln, QStringList &list)
 {
@@ -156,11 +202,17 @@ int mupp_script_read(const char *fln, QStringList &list)
 
 //------------------------------------------------------------------------
 /**
- * <p>check if a bash environment variable exists.
+ * @brief Checks if a bash environment variable exists and is non-empty.
  *
- * @param str name of bash variable to be checked.
+ * This function verifies the existence of a bash environment variable by
+ * querying the system environment. The variable name can be specified with
+ * or without the leading '$' symbol, as it will be removed internally.
  *
- * @return true if the bash variable exists, false otherwise.
+ * @param str name of the bash variable to be checked (with or without '$' prefix)
+ *
+ * @return true if the bash variable exists and has a non-empty value, false otherwise
+ *
+ * @see mupp_script_syntax_check()
  */
 bool mupp_bash_variable_exists(const QString str)
 {
@@ -177,11 +229,30 @@ bool mupp_bash_variable_exists(const QString str)
 
 //------------------------------------------------------------------------
 /**
- * <p>checks the mupp script syntax.
+ * @brief Validates the syntax of mupp script commands.
  *
- * @param list mupp script content.
+ * This function performs comprehensive validation of mupp script commands,
+ * including:
+ * - Verification of command syntax and required parameters
+ * - Validation of file paths and bash environment variables
+ * - Checking file extensions for plot and macro outputs
+ * - Ensuring variable definitions are properly linked to collections
+ * - Verifying collection indices are within valid ranges
  *
- * @return 0 on success, negative numbers otherwise.
+ * The function tracks defined variables and ensures they are properly linked
+ * to collections before use. It also validates that all collections referenced
+ * in the script have been loaded.
+ *
+ * @param list reference to QStringList containing the parsed mupp script commands
+ *
+ * @return 0 on success, negative values indicating different types of errors:
+ *         -1: general syntax error
+ *         -2: invalid file extension or empty bash variable
+ *         -3: unrecognized command or collection out of range
+ *         -4: no data loaded or internal consistency error
+ *         -5: variable not defined before linking
+ *
+ * @see mupp_script_read(), mupp_bash_variable_exists()
  */
 int mupp_script_syntax_check(QStringList &list)
 {
@@ -439,14 +510,22 @@ int mupp_script_syntax_check(QStringList &list)
 
 //------------------------------------------------------------------------
 /**
- * <p>Depending on whether a script or gui application is wished, select
+ * @brief Factory function to create the appropriate Qt application object.
- * the proper Qt application class.
  *
- * @param argc
+ * This function selects and creates the proper Qt application class based on
- * @param argv
+ * whether GUI or console mode is required. It creates a QApplication instance
- * @param gui if true, the gui is wanted, otherwise the script is called.
+ * for GUI mode (which supports widgets and graphics) or a QCoreApplication
+ * instance for script/console mode (which is lighter and has no GUI support).
  *
- * @return the request qt application
+ * @param argc reference to the argument count from main()
+ * @param argv argument vector from main() containing command-line arguments
+ * @param gui if true, a GUI application (QApplication) is created;
+ *            if false, a console application (QCoreApplication) is created
+ *
+ * @return pointer to the created Qt application object (either QApplication
+ *         or QCoreApplication depending on the gui parameter)
+ *
+ * @see main()
  */
 QCoreApplication* createApplication(int &argc, char *argv[], bool gui)
 {
@@ -458,15 +537,39 @@ QCoreApplication* createApplication(int &argc, char *argv[], bool gui)
 
 //------------------------------------------------------------------------
 /**
- * <p>Main mupp application. mupp stands for muon parameter plotter. It allows
+ * @brief Main entry point of the mupp application.
- * to plot the parameters of db- or dat-files. The typical use case is e.g.
- * plotting parameters of muSR fits as function of temperature, pressure,
- * energy, etc.
  *
- * @param argc
+ * mupp (muon parameter plotter) is an application designed to visualize
- * @param argv
+ * muSR fit parameters from db-files, dat-files, or msr-files. The typical
+ * use case is plotting fit parameters as a function of experimental conditions
+ * such as temperature, pressure, magnetic field, energy, etc.
  *
- * @return return value of the Qt application
+ * The application supports two operational modes:
+ * - **GUI mode**: Interactive graphical interface for data exploration,
+ *   parameter selection, and plot generation
+ * - **Script mode**: Batch processing using script files for automated
+ *   plotting and analysis
+ *
+ * Command-line usage:
+ * @code
+ * mupp [OPTIONS] [[--path <fit-param-path>] <fit-param-file-names>]
+ * @endcode
+ *
+ * Processing flow:
+ * 1. Parse command-line arguments
+ * 2. Handle help (-h, --help) and version (-v, --version) requests
+ * 3. Process script mode (-s, --script) or file list mode
+ * 4. Create appropriate Qt application (GUI or console)
+ * 5. Initialize either PmuppGui or PmuppScript
+ * 6. Enter Qt event loop
+ *
+ * @param argc argument count from the command line
+ * @param argv argument vector containing command-line arguments
+ *
+ * @return 0 on successful execution, negative values on error:
+ *         -1: file or script errors, invalid arguments
+ *
+ * @see PmuppGui, PmuppScript, createApplication()
  */
 int main(int argc, char *argv[])
 {

src/musredit_qt6/mupp/mupp.h

@@ -27,6 +27,15 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file mupp.h
+ *
+ * @brief Header file for mupp (muon parameter plotter) main application.
+ *
+ * This header defines constants and data structures used throughout the mupp
+ * application for inter-process communication and application configuration.
+ */
+
 #ifndef _MUPP_H_
 #define _MUPP_H_
 
@@ -35,13 +44,32 @@
 #include <sys/msg.h>
 #include <sys/stat.h>
 
+/**
+ * @brief Maximum number of recent files to be tracked.
+ *
+ * This constant defines the number of recently opened files that should be
+ * stored and displayed in the application's file menu.
+ */
 #define MAX_RECENT_FILES 5
 
+/**
+ * @brief Maximum size of the message text buffer.
+ *
+ * This constant defines the maximum number of characters that can be stored
+ * in the message buffer for inter-process communication.
+ */
 #define PMUPP_MAX_MTEXT 512
 
+/**
+ * @brief Message buffer structure for inter-process communication.
+ *
+ * This structure is used for sending messages between processes using the
+ * System V message queue API. It follows the standard System V message
+ * buffer format with a type field and a character array for the message body.
+ */
 struct mbuf {
-  long mtype;                  // message type
+  long mtype;                  ///< message type identifier for message routing
-  char mtext[PMUPP_MAX_MTEXT]; // message body
+  char mtext[PMUPP_MAX_MTEXT]; ///< message body containing the actual message data
 };
 
 #endif // _MUPP_H_