improve the doxygen docu of musrStep.

src/musredit_qt6/musrStep/PMusrStep.cpp

@@ -27,6 +27,18 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PMusrStep.cpp
+ * @brief Implementation of the PMusrStep and PModSelect dialog classes.
+ * @details This file contains the implementation of the GUI dialogs used
+ * by the musrStep application to modify fit parameter step sizes in
+ * muSR msr-files.
+ *
+ * @author Andreas Suter
+ * @date 2007-2025
+ * @copyright GNU General Public License v2 or later
+ */
+
 #include <QMessageBox>
 #include <QString>
 #include <QStringList>
@@ -48,7 +60,14 @@
 
 //+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
+ * @brief Constructor for the PModSelect dialog.
+ * @details Creates and initializes the dialog UI with the following controls:
+ * - "Scale by Factor" button with associated factor input field
+ * - "Absolute Value" checkbox to toggle between multiplicative and absolute scaling
+ * - "Scale Automatically" button for automatic scaling based on parameter names
+ * - "Cancel" button to close the dialog without applying changes
  *
+ * @param parent Pointer to the parent widget (default: Q_NULLPTR)
  */
 PModSelect::PModSelect(QWidget *parent) :
   QDialog(parent)
@@ -91,8 +110,12 @@ PModSelect::PModSelect(QWidget *parent) :
 
 //-------------------------------------------------------------------------
 /**
- * @brief PModSelect::absoluteValueStateChanged
+ * @brief Handles state changes of the absolute value checkbox.
- * @param ival
+ * @details Updates the UI labels to reflect the current mode:
+ * - When unchecked: Shows "Factor" label and "Scale by Factor" button text
+ * - When checked: Shows "Value" label and "Set Abs. Value" button text
+ *
+ * @param ival The new checkbox state (Qt::Checked or Qt::Unchecked)
  */
 void PModSelect::absoluteValueStateChanged(int ival)
 {
@@ -107,7 +130,10 @@ void PModSelect::absoluteValueStateChanged(int ival)
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Triggers automatic scaling of selected parameters.
+ * @details Emits the scale() signal with automatic=true and a default
+ * factor of 0.01. The parent dialog will then apply scaling factors
+ * based on parameter naming conventions using its lookupTable() method.
  */
 void PModSelect::scaleAuto()
 {
@@ -117,7 +143,10 @@ void PModSelect::scaleAuto()
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Reads the user-specified factor and emits the scale signal.
+ * @details Retrieves the factor value from the input field and the
+ * absolute value checkbox state, then emits the scale() signal with
+ * automatic=false to indicate manual scaling mode.
  */
 void PModSelect::getFactor()
 {
@@ -130,7 +159,21 @@ void PModSelect::getFactor()
 
 //+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
+ * @brief Constructor for the PMusrStep main dialog.
+ * @details Initializes the dialog with the following operations:
+ * 1. Sets up the window title and icon based on the current theme
+ * 2. Reads and parses the msr-file to extract fit parameters
+ * 3. Creates the parameter table with columns for name, value, and step
+ * 4. Sets up selection buttons (Check Specific, Check All, Uncheck All)
+ * 5. Sets up modification buttons (Modify Automatic, Modify Selected)
+ * 6. Sets up action buttons (Save&Quit, Cancel)
+ * 7. Creates the PModSelect sub-dialog for detailed modification options
  *
+ * The dialog height is automatically adjusted based on the number of
+ * parameters, with a maximum limit based on screen resolution.
+ *
+ * @param fln Path to the msr-file to open and edit
+ * @param parent Pointer to the parent widget (default: Q_NULLPTR)
  */
 PMusrStep::PMusrStep(const char *fln, QWidget *parent) :
   QDialog(parent),
@@ -257,7 +300,16 @@ PMusrStep::PMusrStep(const char *fln, QWidget *parent) :
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Handles changes to cells in the parameter table.
+ * @details Performs validation when table cells are modified:
+ * - Column 0 (name): Prevents selection of fixed parameters (step == 0)
+ * - Column 2 (step): Validates that entered values are valid numbers
  *
+ * If an invalid step value is entered, the cell is restored to its
+ * previous value from fParamVec.
+ *
+ * @param row The row index of the changed cell
+ * @param column The column index of the changed cell
  */
 void PMusrStep::handleCellChanged(int row, int column)
 {
@@ -283,7 +335,10 @@ void PMusrStep::handleCellChanged(int row, int column)
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Allows selection of parameters matching a template string.
+ * @details Opens an input dialog where the user can enter a template string.
+ * All parameters whose names contain this template (case-sensitive) are
+ * then checked, except for fixed parameters (step == 0 or "0.0").
  */
 void PMusrStep::checkSpecific()
 {
@@ -305,7 +360,9 @@ void PMusrStep::checkSpecific()
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Selects all non-fixed parameters in the table.
+ * @details Iterates through all rows and checks parameters whose step
+ * value is not "0" or "0.0" (fixed parameters remain unchecked).
  */
 void PMusrStep::checkAll()
 {
@@ -319,7 +376,9 @@ void PMusrStep::checkAll()
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Deselects all parameters in the table.
+ * @details Iterates through all rows and unchecks every parameter,
+ * regardless of whether it is fixed or not.
  */
 void PMusrStep::unCheckAll()
 {
@@ -330,7 +389,10 @@ void PMusrStep::unCheckAll()
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Applies automatic step size modification to all non-fixed parameters.
+ * @details Iterates through all parameters and applies automatic scaling
+ * using lookupTable() and adoptStep(). Fixed parameters (step == 0) are
+ * skipped. Both the table display and the internal fParamVec are updated.
  */
 void PMusrStep::modifyAuto()
 {
@@ -350,7 +412,10 @@ void PMusrStep::modifyAuto()
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Opens the modification dialog for checked parameters.
+ * @details Shows the PModSelect dialog, which allows the user to choose
+ * between automatic scaling and manual factor-based scaling for the
+ * currently selected parameters.
  */
 void PMusrStep::modifyChecked()
 {
@@ -359,7 +424,14 @@ void PMusrStep::modifyChecked()
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Processes the scaling selection from the PModSelect dialog.
+ * @details Applies the specified scaling operation to all checked parameters.
+ * If automatic mode is selected, the factor is determined by lookupTable()
+ * for each parameter individually.
  *
+ * @param automatic If true, use automatic scaling based on parameter names
+ * @param factor The scaling factor (used when automatic is false)
+ * @param absVal If true, factor is used as absolute value; if false, as multiplier
  */
 void PMusrStep::handleModSelect(bool automatic, double factor, bool absVal)
 {
@@ -378,7 +450,9 @@ void PMusrStep::handleModSelect(bool automatic, double factor, bool absVal)
 
 //-------------------------------------------------------------------------
 /**
- *
+ * @brief Saves the modified msr-file and closes the dialog.
+ * @details Calls writeMsrFile() to save all modifications, then
+ * accepts the dialog to close it with a success status.
  */
 void PMusrStep::saveAndQuit()
 {
@@ -388,7 +462,11 @@ void PMusrStep::saveAndQuit()
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Initializes a PParam structure with empty strings.
+ * @details Sets all fields of the parameter structure to empty QString
+ * objects. Used before populating a new parameter from file data.
  *
+ * @param param Reference to the PParam structure to initialize
  */
 void PMusrStep::initParam(PParam &param)
 {
@@ -403,7 +481,21 @@ void PMusrStep::initParam(PParam &param)
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Determines the appropriate step size factor based on parameter name.
+ * @details Uses common muSR parameter naming conventions to identify
+ * parameter types and return appropriate scaling factors:
+ * - freq, frq, field: factor = 1e-3 (high precision for frequency/field)
+ * - lambda, sigma, rlx, rate: factor = 0.1 (relaxation rates)
+ * - phase, phs: factor = 5.0 (absolute value, for phase parameters)
+ * - N0, Nrm, N_bkg, Bgr: factor = 0.01 (normalization/background)
+ * - default: factor = 0.01
  *
+ * The comparison is case-insensitive and matches the start of the
+ * parameter name.
+ *
+ * @param str The parameter name to look up
+ * @param absVal Output flag set to true if factor should be used as absolute value
+ * @return The scaling factor to apply
  */
 double PMusrStep::lookupTable(const QString str, bool &absVal)
 {
@@ -435,7 +527,15 @@ double PMusrStep::lookupTable(const QString str, bool &absVal)
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Calculates the new step value based on current value and factor.
+ * @details Computes the new step size using either:
+ * - Absolute mode (absVal=true): Returns the factor directly as the step
+ * - Multiplicative mode (absVal=false): Returns factor * current_value
  *
+ * @param str The current parameter value as a string
+ * @param factor The scaling factor to apply
+ * @param absVal If true, return factor directly; if false, multiply by value
+ * @return The new step value as a QString
  */
 QString PMusrStep::adoptStep(const QString str, double factor, bool absVal)
 {
@@ -453,7 +553,19 @@ QString PMusrStep::adoptStep(const QString str, double factor, bool absVal)
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Reads and parses the FITPARAMETER block from the msr-file.
+ * @details Opens the msr-file specified in fMsrFileName and extracts
+ * all parameters from the FITPARAMETER block (between FITPARAMETER
+ * and THEORY keywords). Each parameter line must have either 5 or 7
+ * space-separated fields:
+ * - 5 fields: number, name, value, step, posErr
+ * - 7 fields: above plus boundLow, boundHigh
  *
+ * Comment lines (starting with #) and empty lines are ignored.
+ *
+ * @return 1 on success
+ * @return -1 if file cannot be opened
+ * @return -2 if a parameter line has invalid format
  */
 int PMusrStep::readMsrFile()
 {
@@ -512,7 +624,15 @@ int PMusrStep::readMsrFile()
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Writes the modified parameters back to the msr-file.
+ * @details Reads the entire original msr-file, then rewrites it with
+ * updated step values in the FITPARAMETER block. All other content
+ * is preserved unchanged. A "*** FIT DID NOT CONVERGE ***" marker is
+ * appended to indicate the file has been modified.
  *
+ * @return 1 on success
+ * @return -1 if input file cannot be opened for reading
+ * @return -2 if output file cannot be opened for writing
  */
 int PMusrStep::writeMsrFile()
 {
@@ -567,7 +687,14 @@ int PMusrStep::writeMsrFile()
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Extracts a single line from a byte array at the given position.
+ * @details Searches for the next newline character starting at idx and
+ * extracts the text between the current position and the newline.
+ * The idx parameter is updated to point to the character after the newline.
  *
+ * @param data Reference to the byte array containing file data
+ * @param idx Reference to the current position index (updated to next line start)
+ * @return The extracted line as a QString, or empty string if no newline found
  */
 QString PMusrStep::getLine(QByteArray &data, int &idx)
 {
@@ -584,7 +711,19 @@ QString PMusrStep::getLine(QByteArray &data, int &idx)
 
 //-------------------------------------------------------------------------
 /**
+ * @brief Reconstructs a parameter line with updated values.
+ * @details Searches fParamVec for a parameter matching the given line,
+ * then formats a new parameter line with proper field widths:
+ * - Column 1 (10 chars, right-aligned): parameter number
+ * - Column 2 (12+ chars, left-aligned): parameter name
+ * - Columns 3-5 (11 chars each): value, step, posErr
+ * - Columns 6-7 (11 chars each, optional): boundLow, boundHigh
  *
+ * The parameter is identified by finding its name sandwiched between
+ * spaces in the input string to avoid partial matches.
+ *
+ * @param str The original parameter line to update
+ * @return The reconstructed parameter line, or empty string if no match found
  */
 QString PMusrStep::updateParamLine(const QString str)
 {

src/musredit_qt6/musrStep/PMusrStep.h

@@ -27,6 +27,17 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PMusrStep.h
+ * @brief Header file for the PMusrStep and PModSelect dialog classes.
+ * @details This file declares the classes and structures used by the musrStep
+ * application to modify fit parameter step sizes in muSR msr-files.
+ *
+ * @author Andreas Suter
+ * @date 2007-2025
+ * @copyright GNU General Public License v2 or later
+ */
+
 #ifndef _PMUSRSTEP_H_
 #define _PMUSRSTEP_H_
 
@@ -41,84 +52,260 @@
 #include <QCheckBox>
 #include <QLineEdit>
 
+/**
+ * @struct PParam
+ * @brief Structure representing a single fit parameter from an msr-file.
+ * @details This structure holds all components of a FITPARAMETER line
+ * from a musrfit msr-file, including the parameter number, name, value,
+ * step size, positive error, and optional boundary constraints.
+ */
 struct PParam {
-  QString number;
+  QString number;     ///< Parameter number (index) in the msr-file
-  QString name;
+  QString name;       ///< Parameter name identifier
-  QString value;
+  QString value;      ///< Current parameter value
-  QString step;
+  QString step;       ///< Step size for the fit (0 means fixed parameter)
-  QString posErr;
+  QString posErr;     ///< Positive error estimate
-  QString boundLow;
+  QString boundLow;   ///< Lower boundary constraint (optional)
-  QString boundHigh;
+  QString boundHigh;  ///< Upper boundary constraint (optional)
 };
 
 //+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+/**
+ * @class PModSelect
+ * @brief Dialog for selecting modification options for parameter step sizes.
+ * @details This dialog provides the user interface for choosing how to modify
+ * selected parameter step sizes. It offers two main options:
+ * - Scale by a user-specified factor (multiplicative or absolute value)
+ * - Automatic scaling based on parameter naming conventions
+ *
+ * The dialog emits a scale() signal when the user makes a selection,
+ * which is then processed by the parent PMusrStep dialog.
+ */
 class PModSelect : public QDialog
 {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Constructor for PModSelect dialog.
+     * @param parent Pointer to the parent widget (default: Q_NULLPTR)
+     */
     PModSelect(QWidget *parent=Q_NULLPTR);
 
   signals:
+    /**
+     * @brief Signal emitted when user selects a scaling operation.
+     * @param automatic If true, use automatic scaling based on parameter names;
+     *                  if false, use the provided factor value
+     * @param factor The scaling factor to apply (used when automatic is false)
+     * @param absVal If true, factor is used as an absolute value;
+     *               if false, factor is used as a multiplier
+     */
     void scale(bool automatic, double factor, bool absVal);
 
   private slots:
-    void absoluteValueStateChanged(int);
+    /**
+     * @brief Slot called when the absolute value checkbox state changes.
+     * @details Updates the UI labels to reflect whether the factor will be
+     * used as a multiplier or as an absolute value.
+     * @param ival The new checkbox state (Qt::Checked or Qt::Unchecked)
+     */
+    void absoluteValueStateChanged(int ival);
+
+    /**
+     * @brief Slot that triggers automatic scaling of selected parameters.
+     * @details Emits the scale() signal with automatic=true, causing the
+     * parent dialog to apply scaling factors based on parameter naming conventions.
+     */
     void scaleAuto();
+
+    /**
+     * @brief Slot that applies the user-specified factor to selected parameters.
+     * @details Reads the factor value from the input field and the absolute
+     * value checkbox state, then emits the scale() signal with these values.
+     */
     void getFactor();
 
   private:
-    std::unique_ptr<QCheckBox> fAbsVal;
+    std::unique_ptr<QCheckBox> fAbsVal;           ///< Checkbox for absolute value mode
-    std::unique_ptr<QLabel> fFactorLabel;
+    std::unique_ptr<QLabel> fFactorLabel;         ///< Label for the factor input field
-    std::unique_ptr<QLineEdit> fFactorLineEdit;
+    std::unique_ptr<QLineEdit> fFactorLineEdit;   ///< Input field for the scaling factor
-    std::unique_ptr<QPushButton> fScaleByFactor;
+    std::unique_ptr<QPushButton> fScaleByFactor;  ///< Button to apply factor scaling
-    std::unique_ptr<QPushButton> fScaleAutomatic;
+    std::unique_ptr<QPushButton> fScaleAutomatic; ///< Button to apply automatic scaling
-    std::unique_ptr<QPushButton> fCancel;
+    std::unique_ptr<QPushButton> fCancel;         ///< Button to cancel the dialog
 };
 
 //+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+/**
+ * @class PMusrStep
+ * @brief Main dialog class for the musrStep application.
+ * @details This class implements the main user interface for viewing and
+ * modifying fit parameter step sizes in muSR msr-files. It provides:
+ * - A table view displaying all fit parameters with their values and step sizes
+ * - Selection mechanisms for choosing which parameters to modify
+ * - Automatic and manual step size adjustment options
+ * - File I/O for reading and writing msr-files
+ *
+ * The automatic step size adjustment uses a lookup table based on common
+ * muSR parameter naming conventions to determine appropriate step sizes.
+ *
+ * @see PModSelect for the modification options dialog
+ * @see PParam for the parameter data structure
+ */
 class PMusrStep : public QDialog
 {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Constructor for PMusrStep dialog.
+     * @details Initializes the dialog, reads the msr-file, and populates
+     * the parameter table. Sets up all UI elements and signal/slot connections.
+     * @param fln Path to the msr-file to open
+     * @param parent Pointer to the parent widget (default: Q_NULLPTR)
+     */
     PMusrStep(const char *fln, QWidget *parent=Q_NULLPTR);
+
+    /**
+     * @brief Checks if the dialog was initialized successfully.
+     * @details Returns false if the msr-file could not be read or parsed.
+     * @return true if the dialog is valid and ready for use, false otherwise
+     */
     bool isValid() { return fValid; }
 
   private slots:
+    /**
+     * @brief Slot called when a table cell value changes.
+     * @details Validates changes to step values and prevents selection
+     * of fixed parameters (step == 0).
+     * @param row The row index of the changed cell
+     * @param column The column index of the changed cell
+     */
     void handleCellChanged(int row, int column);
+
+    /**
+     * @brief Slot that allows selection of parameters by name template.
+     * @details Opens an input dialog for the user to enter a template string.
+     * All parameters whose names contain the template are selected.
+     */
     void checkSpecific();
+
+    /**
+     * @brief Slot that selects all non-fixed parameters.
+     * @details Checks all parameters except those with step == 0.
+     */
     void checkAll();
+
+    /**
+     * @brief Slot that deselects all parameters.
+     */
     void unCheckAll();
+
+    /**
+     * @brief Slot that applies automatic step modification to all non-fixed parameters.
+     * @details Uses the lookupTable() function to determine appropriate step sizes
+     * based on parameter naming conventions.
+     */
     void modifyAuto();
+
+    /**
+     * @brief Slot that opens the PModSelect dialog for checked parameters.
+     */
     void modifyChecked();
+
+    /**
+     * @brief Slot that saves the modified msr-file and closes the dialog.
+     */
     void saveAndQuit();
+
+    /**
+     * @brief Slot that handles the selection made in the PModSelect dialog.
+     * @details Applies the specified scaling operation to all checked parameters.
+     * @param automatic If true, use automatic scaling based on parameter names
+     * @param factor The scaling factor to apply
+     * @param absVal If true, factor is used as absolute value; if false, as multiplier
+     */
     void handleModSelect(bool automatic, double factor, bool absVal);
 
   private:
-    QString fMsrFileName;
+    QString fMsrFileName;  ///< Path to the currently open msr-file
-    bool fValid;
+    bool fValid;           ///< Flag indicating successful initialization
 
-    QVector<PParam> fParamVec;
+    QVector<PParam> fParamVec;  ///< Vector storing all fit parameters
 
-    std::unique_ptr<QLabel> fTitleLabel;
+    std::unique_ptr<QLabel> fTitleLabel;            ///< Label displaying the file name
-    std::unique_ptr<QTableWidget> fParamTable;
+    std::unique_ptr<QTableWidget> fParamTable;      ///< Table widget for parameter display
-    std::unique_ptr<QPushButton> fCheckSpecific;
+    std::unique_ptr<QPushButton> fCheckSpecific;    ///< Button to select by template
-    std::unique_ptr<QPushButton> fCheckAll;
+    std::unique_ptr<QPushButton> fCheckAll;         ///< Button to select all parameters
-    std::unique_ptr<QPushButton> fUnCheckAll;
+    std::unique_ptr<QPushButton> fUnCheckAll;       ///< Button to deselect all parameters
-    std::unique_ptr<QPushButton> fModifyAuto;
+    std::unique_ptr<QPushButton> fModifyAuto;       ///< Button for automatic modification
-    std::unique_ptr<QPushButton> fModifySelected;
+    std::unique_ptr<QPushButton> fModifySelected;   ///< Button to modify selected parameters
-    std::unique_ptr<QPushButton> fSave;
+    std::unique_ptr<QPushButton> fSave;             ///< Button to save and quit
-    std::unique_ptr<QPushButton> fCancel;
+    std::unique_ptr<QPushButton> fCancel;           ///< Button to cancel without saving
 
-    PModSelect *fModSelect;
+    PModSelect *fModSelect;  ///< Pointer to the modification options dialog
 
+    /**
+     * @brief Initializes a PParam structure with empty strings.
+     * @param param Reference to the PParam structure to initialize
+     */
     void initParam(PParam &param);
+
+    /**
+     * @brief Determines the appropriate step size factor based on parameter name.
+     * @details Uses naming conventions to identify parameter types:
+     * - freq/frq/field: factor = 1e-3
+     * - lambda/sigma/rlx/rate: factor = 0.1
+     * - phase/phs: factor = 5.0 (absolute)
+     * - N0/Nrm/N_bkg/Bgr: factor = 0.01
+     * - default: factor = 0.01
+     * @param str The parameter name to look up
+     * @param absVal Output flag set to true if factor should be used as absolute value
+     * @return The scaling factor to apply
+     */
     double lookupTable(const QString str, bool &absVal);
+
+    /**
+     * @brief Calculates the new step value based on the current value and factor.
+     * @param str The current parameter value as a string
+     * @param factor The scaling factor to apply
+     * @param absVal If true, return factor directly; if false, return factor * value
+     * @return The new step value as a string
+     */
     QString adoptStep(const QString str, double factor, bool absVal);
+
+    /**
+     * @brief Reads and parses the FITPARAMETER block from the msr-file.
+     * @details Populates fParamVec with all parameters found between
+     * FITPARAMETER and THEORY blocks.
+     * @return 1 on success, -1 if file cannot be opened, -2 on parse error
+     */
     int readMsrFile();
+
+    /**
+     * @brief Writes the modified parameters back to the msr-file.
+     * @details Preserves all non-parameter content and updates only the
+     * FITPARAMETER block with new step values.
+     * @return 1 on success, -1 if input file cannot be opened,
+     *         -2 if output file cannot be opened
+     */
     int writeMsrFile();
+
+    /**
+     * @brief Extracts a single line from a byte array.
+     * @param data Reference to the byte array containing file data
+     * @param idx Reference to the current position index (updated on return)
+     * @return The extracted line as a QString
+     */
     QString getLine(QByteArray &data, int &idx);
+
+    /**
+     * @brief Reconstructs a parameter line with updated values.
+     * @details Formats the parameter line with proper field widths for
+     * msr-file compatibility.
+     * @param str The original parameter line
+     * @return The updated parameter line, or empty string if not a parameter line
+     */
     QString updateParamLine(const QString str);
 };
 

src/musredit_qt6/musrStep/musrStep.cpp

@@ -1,3 +1,47 @@
+/***************************************************************************
+
+  musrStep.cpp
+
+  Author: Andreas Suter
+  e-mail: andreas.suter@psi.ch
+
+***************************************************************************/
+
+/***************************************************************************
+ *   Copyright (C) 2007-2025 by Andreas Suter                              *
+ *   andreas.suter@psi.ch                                                  *
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 2 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *                                                                         *
+ *   This program is distributed in the hope that it will be useful,       *
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
+ *   GNU General Public License for more details.                          *
+ *                                                                         *
+ *   You should have received a copy of the GNU General Public License     *
+ *   along with this program; if not, write to the                         *
+ *   Free Software Foundation, Inc.,                                       *
+ *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
+ ***************************************************************************/
+
+/**
+ * @file musrStep.cpp
+ * @brief Main entry point for the musrStep application.
+ * @details musrStep is a Qt-based GUI application for adjusting fit parameter
+ * step sizes in muSR msr-files. It provides an interactive interface to view,
+ * select, and modify the step values of fit parameters used by musrfit.
+ *
+ * The application supports both automatic step size adjustment based on
+ * parameter naming conventions and manual scaling by user-defined factors.
+ *
+ * @author Andreas Suter
+ * @date 2007-2025
+ * @copyright GNU General Public License v2 or later
+ */
+
 #include <iostream>
 #include <cstring>
 
@@ -11,6 +55,13 @@
 #include "PMusrStep.h"
 
 //-------------------------------------------------------------------------
+/**
+ * @brief Prints the command-line syntax and usage information to stdout.
+ * @details This function displays the available command-line options:
+ * - \<fln\>: The msr-file name to open and edit
+ * - -v, --version: Display git version information
+ * - -h, --help: Display this help message
+ */
 void musrStep_syntax()
 {
   std::cout << std::endl;
@@ -22,6 +73,19 @@ void musrStep_syntax()
 }
 
 //-------------------------------------------------------------------------
+/**
+ * @brief Main entry point for the musrStep application.
+ * @details Parses command-line arguments and launches the musrStep GUI.
+ *
+ * The application expects exactly one argument which can be:
+ * - A path to an msr-file to open
+ * - -v or --version to display version information
+ * - -h or --help to display usage information
+ *
+ * @param argc Number of command-line arguments
+ * @param argv Array of command-line argument strings
+ * @return 0 on success, 1 on error or invalid usage
+ */
 int main(int argc, char *argv[])
 {
   char fln[1024];