improve the doxygen docu of PmuppScript.* (musredit_qt6).

src/musredit_qt6/mupp/PmuppScript.cpp

@@ -27,6 +27,44 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PmuppScript.cpp
+ *
+ * @brief Implementation of the mupp scripting interface for batch processing.
+ *
+ * This file implements the non-interactive scripting system for mupp, enabling
+ * automated batch processing of parameter data analysis and plotting tasks.
+ *
+ * Key functionality implemented:
+ * - Script command parsing and execution
+ * - Path management with environment variable expansion
+ * - Data collection loading and selection
+ * - X-Y axis parameter configuration
+ * - Variable expression evaluation and storage
+ * - ROOT macro generation with full plot specification
+ * - Batch mode plot creation via ROOT subprocess
+ * - Label formatting for publication-quality plots
+ *
+ * Script command processing:
+ * The executeScript() method processes commands sequentially, maintaining
+ * state throughout execution. Each command type (loadPath, load, select,
+ * x, y, var, norm, plot, macro) has a dedicated handler method.
+ *
+ * ROOT macro generation:
+ * The macro() method creates complete ROOT C++ macros including:
+ * - Data array definitions
+ * - TGraphAsymmErrors objects for error bars
+ * - Canvas and styling setup
+ * - Axis labels and ranges
+ * - Marker and color configuration
+ * - Optional normalization
+ *
+ * Variable system:
+ * Variables are mathematical expressions combining collection parameters.
+ * The var_cmd() method integrates with PVarHandler for expression parsing
+ * and evaluation, enabling derived quantity calculations.
+ */
+
 #include <cmath>
 #include <iostream>
 
@@ -43,8 +81,16 @@
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::PmuppScript. Ctor
- * @param script source
+ * @brief Constructor for the script interpreter.
+ *
+ * Initializes the script execution environment with default settings:
+ * - Load path: current directory
+ * - Save path: current directory
+ * - Selection state: nothing selected
+ * - Normalization: disabled
+ * - Administration object for configuration access
+ *
+ * @param script list of script commands to be executed
  */
 PmuppScript::PmuppScript(QStringList script) :
   fScript(script)
@@ -59,8 +105,33 @@ PmuppScript::PmuppScript(QStringList script) :
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::executeScript. Handles the script commands.
- * @return 0 on success.
+ * @brief Executes all script commands sequentially.
+ *
+ * Processes each command in the script list, dispatching to appropriate
+ * handler methods based on command type. Maintains state throughout
+ * execution including:
+ * - Loaded data collections
+ * - Current selection
+ * - Plot configurations
+ * - Variable definitions
+ *
+ * Command dispatch table:
+ * - "loadPath" → setLoadPath()
+ * - "savePath" → setSavePath()
+ * - "load " → loadCollection()
+ * - "selectAll" → selectAll()
+ * - "select " → select()
+ * - "x" → addX()
+ * - "y" → addY()
+ * - "norm" → sets fNorm flag
+ * - "plot" → plot()
+ * - "macro" → macro()
+ * - "var" → var_cmd()
+ * - "col" → (handled internally by var)
+ *
+ * Emits finished() signal upon completion or error.
+ *
+ * @return 0 on success, non-zero error code on failure
  */
 int PmuppScript::executeScript()
 {
@@ -117,9 +188,22 @@ int PmuppScript::executeScript()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::setLoadPath. Sets the load path (where to look for input
- * data.
- * @param cmd set load path command string.
+ * @brief Sets the load path for input data files.
+ *
+ * Parses the loadPath command string and extracts the directory path.
+ * Supports environment variable expansion: variables prefixed with '$'
+ * are replaced with their values from the system environment.
+ *
+ * Path processing:
+ * 1. Removes "loadPath " prefix from command
+ * 2. Tokenizes path by '/' separator
+ * 3. Expands environment variables ($VAR_NAME)
+ * 4. Reconstructs full path with '/' separators
+ *
+ * Example: "loadPath $HOME/data/musrfit/"
+ * → "/home/user/data/musrfit/"
+ *
+ * @param cmd loadPath command string including path specification
  */
 void PmuppScript::setLoadPath(const QString cmd)
 {
@@ -151,9 +235,21 @@ void PmuppScript::setLoadPath(const QString cmd)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::setSavePath. Sets the save path (where to save the output
- * files.
- * @param cmd save path command string.
+ * @brief Sets the save path for output files.
+ *
+ * Parses the savePath command string and extracts the directory path.
+ * Uses the same environment variable expansion mechanism as setLoadPath().
+ *
+ * Path processing:
+ * 1. Removes "savePath " prefix from command
+ * 2. Tokenizes path by '/' separator
+ * 3. Expands environment variables ($VAR_NAME)
+ * 4. Reconstructs full path with '/' separators
+ *
+ * Example: "savePath $HOME/plots/"
+ * → "/home/user/plots/"
+ *
+ * @param cmd savePath command string including path specification
  */
 void PmuppScript::setSavePath(const QString cmd)
 {
@@ -185,9 +281,20 @@ void PmuppScript::setSavePath(const QString cmd)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::loadCollection. Load collection command
- * @param str load collection command string
- * @return 0 on success.
+ * @brief Loads a data collection from file.
+ *
+ * Parses the load command to extract the filename, prepends the load path,
+ * and reads the parameter data file via the PParamDataHandler.
+ *
+ * Processing steps:
+ * 1. Removes "load " prefix from command string
+ * 2. Trims whitespace from filename
+ * 3. Prepends fLoadPath to create full file path
+ * 4. Calls ReadParamFile() to load the data
+ *
+ * @param str load command string (format: "load filename.ext")
+ *
+ * @return 0 on success, 1 if file reading fails
  */
 int PmuppScript::loadCollection(const QString str)
 {
@@ -208,9 +315,21 @@ int PmuppScript::loadCollection(const QString str)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::select. Select collection command.
- * @param str selection command string
+ * @brief Selects a specific collection for plotting.
+ *
+ * Parses the select command to identify a collection by either:
+ * - Numeric index (0, 1, 2, ...)
+ * - Collection name string
+ *
+ * The selected collection becomes the target for subsequent x and y
+ * commands. Sets fSelected to the collection index.
+ *
+ * @param str select command string (format: "select <index|name>")
+ *
  * @return 0 on success
+ * @return -1 wrong command syntax
+ * @return -2 collection index out of range
+ * @return -3 collection name not found
  */
 int PmuppScript::select(const QString str)
 {
@@ -247,8 +366,15 @@ int PmuppScript::select(const QString str)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::selectAll. Select all collections
- * @return 0 on success
+ * @brief Selects all loaded collections for plotting.
+ *
+ * Enables batch plotting mode where subsequent x and y commands apply
+ * to all collections. Sets fSelected to -1 (all-selected state).
+ *
+ * This mode is useful for creating overlay plots showing multiple
+ * data sets with the same parameter axes.
+ *
+ * @return 0 on success, -1 if no collections are loaded
  */
 int PmuppScript::selectAll()
 {
@@ -265,9 +391,29 @@ int PmuppScript::selectAll()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::addX. Add label to x-axis
- * @param str label string
+ * @brief Adds a parameter label to the X-axis.
+ *
+ * Configures the X-axis (independent variable) for the plot. The label
+ * can be either:
+ * - A parameter name from the collection (e.g., "dataT", "dataB")
+ * - A defined variable expression
+ *
+ * Behavior depends on selection state:
+ * - fSelected == -2: Error (no selection made)
+ * - fSelected == -1: Applies to all collections (creates fPlotInfo entries)
+ * - fSelected >= 0: Applies to specific collection (sets fPlotEntry)
+ *
+ * Validation:
+ * - Checks if label exists in collection(s) or as a variable
+ * - Reports error if label not found
+ *
+ * @param str x command string (format: "x <label>")
+ *
  * @return 0 on success
+ * @return -1 wrong command syntax
+ * @return -2 no collection selected
+ * @return -3 selected collection not found
+ * @return -4 label not found in collection or variables
  */
 int PmuppScript::addX(const QString str)
 {
@@ -354,9 +500,33 @@ int PmuppScript::addX(const QString str)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::addY. Add label to y-axis.
- * @param str label string
+ * @brief Adds one or more parameter labels to the Y-axis.
+ *
+ * Configures the Y-axis (dependent variable(s)) for the plot. Multiple
+ * Y-axis parameters can be specified in a single command, enabling
+ * multi-curve plots.
+ *
+ * Each label can be either:
+ * - A parameter name from the collection
+ * - A defined variable expression
+ *
+ * Behavior depends on selection state:
+ * - fSelected == -2: Error (no selection made)
+ * - fSelected == -1: Applies to all collections (updates fPlotInfo)
+ * - fSelected >= 0: Applies to specific collection (updates fPlotEntry,
+ *                   adds to fPlotInfo)
+ *
+ * Validation:
+ * - Checks if each label exists in collection(s) or as a variable
+ * - Reports error on first missing label
+ *
+ * @param str y command string (format: "y <label1> [label2] [label3] ...")
+ *
  * @return 0 on success
+ * @return -1 wrong command syntax (< 2 tokens)
+ * @return -2 no collection selected
+ * @return -3 selected collection not found
+ * @return -4 label not found in collection or variables
  */
 int PmuppScript::addY(const QString str)
 {
@@ -462,9 +632,30 @@ int PmuppScript::addY(const QString str)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::plot. Create root macro and feed it to root in the bash mode.
- * @param str plot script command string
+ * @brief Creates a plot file by generating and executing a ROOT macro.
+ *
+ * This method performs the complete workflow for batch plot creation:
+ * 1. Generates a temporary ROOT C++ macro (__out.C)
+ * 2. Launches root.exe in batch mode to execute the macro
+ * 3. Creates the output plot file (format determined by extension)
+ * 4. Cleans up the temporary macro file
+ *
+ * Supported output formats (via ROOT):
+ * - .pdf - PDF document
+ * - .png - PNG image
+ * - .eps - Encapsulated PostScript
+ * - .svg - Scalable Vector Graphics
+ * - .root - ROOT file
+ *
+ * The method configures environment variables (LD_LIBRARY_PATH/
+ * DYLD_LIBRARY_PATH) to ensure ROOT finds its libraries.
+ *
+ * @param str plot command string (format: "plot output_filename.ext")
+ *
  * @return 0 on success
+ * @return -1 wrong command syntax or macro generation failed
+ * @return -2 failed to create QProcess
+ * @return -3 failed to start root.exe
  */
 int PmuppScript::plot(const QString str)
 {
@@ -519,11 +710,41 @@ int PmuppScript::plot(const QString str)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::macro. Create a root macro
- * @param str macro string command string
- * @param plotFln plot file name. Depending on the extension (*.png, *.pdf, ...)
- * the given a file will be created.
+ * @brief Generates a ROOT C++ macro for plotting.
+ *
+ * Creates a complete, standalone ROOT macro that can be executed
+ * independently. The macro includes:
+ *
+ * Generated content:
+ * - Header with timestamp and filename
+ * - ROOT initialization and style settings
+ * - Data array declarations (xx, yy, error arrays)
+ * - Data population from collections/variables
+ * - TGraphAsymmErrors object creation
+ * - Canvas setup and configuration
+ * - Marker and color styling from configuration
+ * - Axis labels and ranges
+ * - Optional normalization
+ * - Optional SaveAs() call for plot output
+ *
+ * Data handling:
+ * - Retrieves X/Y values from collections or variables
+ * - Handles asymmetric error bars (positive/negative)
+ * - Calculates axis ranges with 5% padding
+ * - Supports normalization to maximum Y value
+ *
+ * Styling:
+ * - Uses marker and color definitions from PmuppAdmin
+ * - Falls back to default black circles if config exhausted
+ * - Applies ROOT formatting for Greek letters and subscripts
+ *
+ * @param str macro command string (format: "macro filename.C")
+ * @param plotFln optional output plot filename (adds SaveAs to macro)
+ *
  * @return 0 on success
+ * @return -1 wrong command syntax
+ * @return -2 failed to open macro file for writing
+ * @return -3 X or Y label data not found (internal error)
  */
 int PmuppScript::macro(const QString str, const QString plotFln)
 {
@@ -756,9 +977,35 @@ int PmuppScript::macro(const QString str, const QString plotFln)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::var_cmd. Variable definition command
- * @param str variable definition command string
+ * @brief Processes a variable definition command.
+ *
+ * Variables enable defining derived quantities as mathematical expressions
+ * combining collection parameters. For example:
+ * - "var amplitude sigma+lambda"
+ * - "var asymmetry (forward-backward)/(forward+backward)"
+ *
+ * Processing steps:
+ * 1. Extracts variable name from command
+ * 2. Checks if variable is linked to a collection (via col command)
+ * 3. Locates optional error variable definition (varNameErr)
+ * 4. Creates PVarHandler for expression parsing and evaluation
+ * 5. Validates variable and stores handler if valid
+ *
+ * Error handling:
+ * - Error variables (ending in "Err") are processed silently
+ * - Invalid expressions write errors to ~/.musrfit/mupp/mupp_err.log
+ * - Error log is displayed and deleted on failure
+ *
+ * Integration with col command:
+ * The "col" command links variables to specific collections, enabling
+ * variable resolution during plot generation.
+ *
+ * @param str var command string (format: "var <name> <expression>")
+ *
  * @return 0 on success
+ * @return 0 if variable not linked to collection (ignored)
+ * @return 0 if error variable (processing deferred)
+ * @return 1 if variable expression is invalid
  */
 int PmuppScript::var_cmd(const QString str)
 {
@@ -814,9 +1061,16 @@ int PmuppScript::var_cmd(const QString str)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::foundLabel find label in collection coll.
- * @param coll collection object
- * @return true if found
+ * @brief Checks if a parameter label exists in a collection.
+ *
+ * Searches the first run of the collection for a parameter matching
+ * the given label. Assumes all runs in a collection have the same
+ * parameter structure.
+ *
+ * @param coll pointer to collection to search
+ * @param label parameter label to find
+ *
+ * @return true if label found in collection, false otherwise
  */
 bool PmuppScript::foundLabel(PmuppCollection *coll, const QString label)
 {
@@ -833,10 +1087,15 @@ bool PmuppScript::foundLabel(PmuppCollection *coll, const QString label)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::foundVariable. Check if a variable is found in the
- * variable handler.
- * @param var variable name
- * @return true if found
+ * @brief Checks if a variable is defined in the variable handler.
+ *
+ * Searches the variable handler vector for a variable with the
+ * specified name. Used to validate variable references in x and y
+ * commands.
+ *
+ * @param var variable name to search for
+ *
+ * @return true if variable found, false otherwise
  */
 bool PmuppScript::foundVariable(const QString var)
 {
@@ -853,10 +1112,15 @@ bool PmuppScript::foundVariable(const QString var)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::getVarIndex. Get index of the variable object given by
- * its name.
- * @param var variable name searched for
- * @return idx of found, -1 otherwise
+ * @brief Gets the index of a variable in the handler vector.
+ *
+ * Searches for a variable by name and returns its position in the
+ * fVarHandler vector. Used during macro generation to retrieve
+ * variable values.
+ *
+ * @param var variable name to search for
+ *
+ * @return variable index (0-based), or -1 if not found
  */
 int PmuppScript::getVarIndex(const QString var)
 {
@@ -873,10 +1137,14 @@ int PmuppScript::getVarIndex(const QString var)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::minMax get minimum and maximum of the data set.
- * @param dvec data set vector
- * @param min resulting minimum
- * @param max resulting maximum
+ * @brief Finds minimum and maximum values in a data vector.
+ *
+ * Scans through the data vector to determine the range. Used for
+ * automatic axis range calculation in plot generation.
+ *
+ * @param dvec data vector to analyze
+ * @param min output parameter: minimum value in vector
+ * @param max output parameter: maximum value in vector
  */
 void PmuppScript::minMax(QVector<double> dvec, double &min, double &max)
 {
@@ -892,9 +1160,29 @@ void PmuppScript::minMax(QVector<double> dvec, double &min, double &max)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::getNicerLabel. Prettify the labels.
- * @param label to be prettified
- * @return prettified label
+ * @brief Converts parameter labels to publication-quality ROOT format.
+ *
+ * Transforms standard parameter names into formatted labels suitable
+ * for publication plots, including:
+ * - Greek letters using ROOT markup (#sigma, #lambda, #alpha)
+ * - Subscripts and superscripts
+ * - Physical units
+ * - Normalization indicators (when fNorm is true)
+ *
+ * Special case handling:
+ * - dataE → "E (keV)"
+ * - dataT → "T (K)"
+ * - dataB → "B (G)"
+ * - sigma → "#sigma (1/#mus)" or normalized version
+ * - lambda → "#lambda (1/#mus)" or normalized version
+ * - rate → "Rate (1/#mus)" or normalized version
+ * - alpha_LR → "#alpha_{LR}" or normalized version
+ * - alpha_TB → "#alpha_{TB}" or normalized version
+ * - others → "label/ max(label)" if normalized
+ *
+ * @param label original parameter label string
+ *
+ * @return formatted label with ROOT markup
  */
 QString PmuppScript::getNicerLabel(const QString label)
 {
@@ -942,9 +1230,18 @@ QString PmuppScript::getNicerLabel(const QString label)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppScript::getCollectionIndex. Get the index of a collection.
- * @param var_name name of the collection
- * @return idx on success, -1 otherwise
+ * @brief Gets the collection index associated with a variable.
+ *
+ * Searches the script for a "col" command linking the variable to a
+ * collection. The col command format is:
+ * "col <collection_idx> -> <variable_name>"
+ *
+ * This association is necessary for variable evaluation, as the
+ * variable needs to know which collection's parameters to use.
+ *
+ * @param var_name variable name to search for
+ *
+ * @return collection index (0-based), or -1 if not found
  */
 int PmuppScript::getCollectionIndex(const QString var_name)
 {