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

src/musredit_qt6/musredit/PGetPlotBlockDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetPlotBlockDialog.cpp
+ * @brief Implementation of the PGetPlotBlockDialog class.
+ * @details This file implements the dialog for creating PLOT blocks in msr
+ * files. It handles user input validation, proper formatting of plot
+ * specifications, and keyboard shortcuts for rapid plot 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>
@@ -40,9 +53,21 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructs the PLOT block dialog.
  *
- * \param helpUrl help url for the PLOT block.
+ * @details Initializes the dialog UI, sets up input validators for numeric
+ * range 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 plot display to ensure proper column alignment.
+ *
+ * @par Input Validators:
+ * - Double validators: X-range lower/upper, Y-range lower/upper
+ *
+ * @par Event Filter:
+ * An event filter is installed to intercept the Return key, allowing users
+ * to quickly add plots by pressing Enter instead of clicking the Add button.
+ *
+ * @param helpUrl URL to the online documentation for PLOT blocks.
  */
 PGetPlotBlockDialog::PGetPlotBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl)
 {
@@ -63,8 +88,32 @@ PGetPlotBlockDialog::PGetPlotBlockDialog(const QString helpUrl) : fHelpUrl(helpU
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Extracts the information of the top part of the dialog, constructs a msr-file PLOT block and
+ * @brief Validates and adds a plot specification to the PLOT block.
- * writes it into the text edit window.
+ *
+ * @details Extracts values from all input fields, validates required fields,
+ * formats the plot block with proper column alignment, and appends it to the
+ * plot text display. After successful addition, the input fields are cleared
+ * and focus returns to the Run List field for the next plot.
+ *
+ * @par Validation Rules:
+ * - Lower X-range (time) is required
+ * - Upper X-range (time) is required
+ * - Y-range is optional, but if provided, both lower and upper must be specified
+ *
+ * @par Plot Type Codes:
+ * - "Single Histo" → 0
+ * - "Asymmetry" → 2
+ * - "MuMinus" → 4
+ * - "NonMusr" → 8
+ *
+ * @par Generated Format:
+ * @code
+ * PLOT <type_code>   (<type description>)
+ * runs     <run_list>
+ * range    <x_low>  <x_high>  [<y_low>  <y_high>]
+ * @endcode
+ *
+ * @note The separator line (###...) is only added for the first plot block.
  */
 void PGetPlotBlockDialog::addPlot()
 {
@@ -154,7 +203,11 @@ void PGetPlotBlockDialog::addPlot()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Generates a help content window showing the description of the PLOT block.
+ * @brief Opens the online help documentation for PLOT 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 PGetPlotBlockDialog::helpContent()
 {
@@ -171,10 +224,18 @@ void PGetPlotBlockDialog::helpContent()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>This event filter is filtering out the return key, and if present adds the current plot.
+ * @brief Event filter to intercept keyboard events.
  *
- * \param obj object which is triggering the event
+ * @details Filters keyboard events to intercept the Return/Enter key press.
- * \param ev the triggered event
+ * When Return is pressed, the current plot values are validated and added
+ * to the plot list via addPlot(). This allows for rapid plot 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 plot
+ *         was added), false otherwise (event is passed to the base class).
  */
 bool PGetPlotBlockDialog::eventFilter( QObject *obj, QEvent *ev )
 {

src/musredit_qt6/musredit/PGetPlotBlockDialog.h

@@ -27,14 +27,71 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetPlotBlockDialog.h
+ * @brief Dialog for creating PLOT blocks in msr files.
+ * @details This header defines the PGetPlotBlockDialog class which provides
+ * a dialog for entering plot parameters needed to create a PLOT block in a
+ * musrfit msr file. Multiple PLOT blocks can be defined to visualize different
+ * aspects of the fit data.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PGetFourierBlockDialog For creating FOURIER blocks
+ * @see PGetAsymmetryRunBlockDialog For creating asymmetry RUN blocks
+ */
+
 #ifndef _PGETPLOTBLOCKDIALOG_H_
 #define _PGETPLOTBLOCKDIALOG_H_
 
 #include "ui_PGetPlotBlockDialog.h"
 
-//--------------------------------------------------------------------------
+//---------------------------------------------------------------------------
 /**
- * <p>Handels content of the PLOT block dialog.
+ * @class PGetPlotBlockDialog
+ * @brief Dialog for creating PLOT blocks in msr files.
+ *
+ * @details This dialog allows users to define plot specifications for
+ * visualizing musrfit data. Multiple plots can be added, each with its
+ * own type, run selection, and axis ranges. The dialog supports keyboard
+ * shortcuts for rapid plot entry.
+ *
+ * @par Plot Types:
+ * | Type | Code | Description |
+ * |------|------|-------------|
+ * | Single Histo | 0 | Single histogram plot |
+ * | Asymmetry | 2 | Asymmetry plot |
+ * | MuMinus | 4 | Mu minus plot |
+ * | NonMusr | 8 | Non-muSR data plot |
+ *
+ * @par Plot Parameters:
+ * - **Type**: Plot type (Single Histo, Asymmetry, MuMinus, NonMusr)
+ * - **Runs**: Space-separated list of run numbers to include
+ * - **X-Range**: Time or x-axis range (both values required)
+ * - **Y-Range**: Asymmetry or y-axis range (optional, both or neither)
+ *
+ * @par Generated Output Format:
+ * The dialog generates properly formatted PLOT blocks:
+ * @code
+ * ###############################################################
+ * PLOT 2   (asymmetry plot)
+ * runs     1 2 3
+ * range    0.0     10.0    -0.3    0.3
+ *
+ * PLOT 0   (single histo plot)
+ * runs     1
+ * range    0.0     10.0
+ * @endcode
+ *
+ * @par User Interaction:
+ * - Press Return/Enter key to quickly add plots
+ * - Input fields are cleared after each plot addition
+ * - Focus returns to the Run List field for rapid entry
+ *
+ * @see PGetFourierBlockDialog For Fourier transform visualization settings
  */
 class PGetPlotBlockDialog : public QDialog, private Ui::PGetPlotBlockDialog
 {
@@ -43,17 +100,36 @@ class PGetPlotBlockDialog : public QDialog, private Ui::PGetPlotBlockDialog
   public:
     PGetPlotBlockDialog(const QString helpUrl);
 
+    /**
+     * @brief Returns all entered plot specifications as formatted text.
+     * @return Complete PLOT block content ready for insertion into an msr file.
+     */
     QString getPlotBlock() { return fPlot_plainTextEdit->toPlainText(); }
 
   public slots:
+    /**
+     * @brief Validates and adds a plot specification to the PLOT block.
+     */
     void addPlot();
+
+    /**
+     * @brief Opens the online help for PLOT blocks.
+     */
     void helpContent();
 
   protected:
+    /**
+     * @brief Event filter to handle keyboard shortcuts.
+     * @details Intercepts the Return key to trigger plot addition,
+     *          allowing for rapid plot 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:
-    QString fHelpUrl; ///< help url for the PLOT block
+    QString fHelpUrl; ///< URL to the online documentation for PLOT blocks.
 };
 
 #endif // _PGETPLOTBLOCKDIALOG_H_