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

src/musredit_qt6/musredit/PGetParameterBlockDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetParameterBlockDialog.cpp
+ * @brief Implementation of the PGetParameterBlockDialog class.
+ * @details This file implements the dialog for creating FITPARAMETER blocks
+ * in msr files. It handles user input validation, proper column formatting
+ * for the msr file format, and keyboard shortcuts for rapid parameter entry.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #include <QLineEdit>
 #include <QValidator>
 #include <QMessageBox>
@@ -41,9 +54,21 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructs the FITPARAMETER block dialog.
  *
- * \param helpUrl help url of the PARAMETER block.
+ * @details Initializes the dialog UI, sets up input validators for numeric
+ * fields, and installs an event filter to capture keyboard shortcuts.
+ * The dialog is created as modal. A monospace font (Courier, 10pt) is used
+ * for the parameter display to ensure proper column alignment.
+ *
+ * @par Input Validators:
+ * - Double validators: parameter value and step size
+ *
+ * @par Event Filter:
+ * An event filter is installed to intercept the Return key, allowing users
+ * to quickly add parameters by pressing Enter instead of clicking the Add button.
+ *
+ * @param helpUrl URL to the online documentation for FITPARAMETER blocks.
  */
 PGetParameterBlockDialog::PGetParameterBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl)
 {
@@ -62,11 +87,18 @@ PGetParameterBlockDialog::PGetParameterBlockDialog(const QString helpUrl) : fHel
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>This event filter is filtering out the return key, and if present adds the current parameters
+ * @brief Event filter to intercept keyboard events.
- * to the parameter list.
  *
- * \param obj object which was generating the event.
+ * @details Filters keyboard events to intercept the Return/Enter key press.
- * \param ev event of the object.
+ * When Return is pressed, the current parameter values are validated and
+ * added to the parameter list via paramAdd(). This allows for rapid
+ * parameter entry without using the mouse to click the Add button.
+ *
+ * @param obj Pointer to the object that generated the event.
+ * @param ev Pointer to the event to be filtered.
+ *
+ * @return true if the event was handled (Return key was pressed and parameter
+ *         was added), false otherwise (event is passed to the base class).
  */
 bool PGetParameterBlockDialog::eventFilter( QObject *obj, QEvent *ev )
 {
@@ -89,7 +121,33 @@ bool PGetParameterBlockDialog::eventFilter( QObject *obj, QEvent *ev )
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Adds a parameter to the text edit window.
+ * @brief Validates and adds a parameter to the FITPARAMETER block.
+ *
+ * @details Collects values from all input fields, validates required fields,
+ * formats the parameter line with proper column alignment, and appends it
+ * to the parameter text display. After successful addition, the input fields
+ * are reset and focus returns to the Name field for the next parameter.
+ *
+ * @par Validation Rules:
+ * - Parameter name is required (cannot be empty)
+ * - Parameter value is required (cannot be empty)
+ * - Parameter step is required (cannot be empty)
+ * - Lower boundary must be "none" or a valid double
+ * - Upper boundary must be "none" or a valid double
+ *
+ * @par Column Formatting:
+ * - Parameter number: right-aligned in 10 character field
+ * - Name: left-aligned, padded to 13 characters
+ * - Value: left-aligned, padded to 10 characters
+ * - Step: left-aligned, padded to 10 characters
+ * - Positive error: always "none" (11 characters)
+ * - Lower boundary: left-aligned, padded to 10 characters (optional)
+ * - Upper boundary: left-aligned, padded to 10 characters (optional)
+ *
+ * @par Post-Addition Actions:
+ * - Parameter number is auto-incremented
+ * - All input fields are cleared (boundaries reset to "none")
+ * - Focus moves to the Name field
  */
 void PGetParameterBlockDialog::paramAdd()
 {
@@ -213,7 +271,11 @@ void PGetParameterBlockDialog::paramAdd()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Generates a help content window showing the description of the FITPARAMETER block.
+ * @brief Opens the online help documentation for FITPARAMETER blocks.
+ *
+ * @details Attempts to open the help URL in the system's default web browser
+ * using QDesktopServices. If the URL is empty, displays an informational message.
+ * If the browser fails to open, displays an error message with a clickable link.
  */
 void PGetParameterBlockDialog::helpContent()
 {

src/musredit_qt6/musredit/PGetParameterBlockDialog.h

@@ -27,14 +27,62 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetParameterBlockDialog.h
+ * @brief Dialog for creating FITPARAMETER blocks in msr files.
+ * @details This header defines the PGetParameterBlockDialog class which provides
+ * a dialog for entering fit parameters needed to create a FITPARAMETER block
+ * in a musrfit msr file. The dialog supports parameter entry with validation
+ * and optional boundary constraints.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PGetFunctionsBlockDialog For creating FUNCTIONS blocks using these parameters
+ * @see PGetTheoryBlockDialog For creating THEORY blocks
+ */
+
 #ifndef _PGETPARAMETERBLOCKDIALOG_H_
 #define _PGETPARAMETERBLOCKDIALOG_H_
 
 #include "ui_PGetParameterBlockDialog.h"
 
-//-----------------------------------------------------------------------------------
+//---------------------------------------------------------------------------
 /**
- * <p>Handles the content of the PARAMETER block dialog.
+ * @class PGetParameterBlockDialog
+ * @brief Dialog for creating FITPARAMETER blocks in msr files.
+ *
+ * @details This dialog allows users to define fit parameters for musrfit.
+ * Each parameter consists of a number, name, initial value, step size, and
+ * optional lower/upper boundaries. Parameters are formatted with proper
+ * column alignment for the msr file format.
+ *
+ * @par Parameter Fields:
+ * - **No**: Parameter number (auto-incremented)
+ * - **Name**: Parameter name (required, max ~12 chars for alignment)
+ * - **Value**: Initial parameter value (required)
+ * - **Step**: Initial step size for minimizer (required)
+ * - **Lower**: Lower boundary ("none" or numeric value)
+ * - **Upper**: Upper boundary ("none" or numeric value)
+ *
+ * @par Generated Output Format:
+ * The dialog generates properly formatted FITPARAMETER lines:
+ * @code
+ * FITPARAMETER
+ *          1 alpha        1.0       0.01      none
+ *          2 beta         0.5       0.001     none       0.0        1.0
+ *          3 frequency    10.5      0.1       none
+ * @endcode
+ *
+ * @par User Interaction:
+ * - Press Return/Enter key to quickly add parameters
+ * - Parameter number auto-increments after each addition
+ * - Input fields are reset after adding a parameter
+ * - Focus returns to the Name field for rapid entry
+ *
+ * @see PGetFunctionsBlockDialog For defining functions using these parameters
  */
 class PGetParameterBlockDialog : public QDialog, private Ui::PGetParameterBlockDialog
 {
@@ -43,17 +91,37 @@ class PGetParameterBlockDialog : public QDialog, private Ui::PGetParameterBlockD
   public:
     PGetParameterBlockDialog(const QString helpUrl);
 
+    /**
+     * @brief Returns all entered parameters as formatted text.
+     * @return Complete FITPARAMETER block content ready for insertion
+     *         into an msr file.
+     */
     QString getParams() { return fParam_plainTextEdit->toPlainText(); }
 
   protected:
+    /**
+     * @brief Event filter to handle keyboard shortcuts.
+     * @details Intercepts the Return key to trigger parameter addition,
+     *          allowing for rapid parameter entry without clicking the Add button.
+     * @param obj The object that generated the event.
+     * @param ev The event to be filtered.
+     * @return true if the event was handled (Return key), false otherwise.
+     */
     bool eventFilter( QObject *obj, QEvent *ev );
 
   private slots:
+    /**
+     * @brief Validates and adds a parameter to the FITPARAMETER block.
+     */
     void paramAdd();
+
+    /**
+     * @brief Opens the online help for FITPARAMETER blocks.
+     */
     void helpContent();
 
   private:
-    QString fHelpUrl; ///< help url of the PARAMETER block description.
+    QString fHelpUrl; ///< URL to the online documentation for FITPARAMETER blocks.
 };
 
 #endif // _PGETPARAMETERBLOCKDIALOG_H_