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

src/musredit_qt6/musredit/PGetFunctionsBlockDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetFunctionsBlockDialog.cpp
+ * @brief Implementation of the PGetFunctionsBlockDialog class.
+ * @details This file implements the dialog for creating FUNCTIONS blocks in msr
+ * files. It handles user input validation using regular expressions to ensure
+ * function definitions follow the required syntax before adding them to the block.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #include <QTextEdit>
 #include <QLineEdit>
 #include <QMessageBox>
@@ -41,9 +54,13 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructs the FUNCTIONS block dialog.
  *
- * \param helpUrl help url for the FUNCTIONS block.
+ * @details Initializes the dialog UI and sets focus to the function input field.
+ * The dialog is created as modal.
+ *
+ * @param helpUrl URL to the online documentation for FUNCTIONS blocks.
+ *                Defaults to empty string if not provided.
  */
 PGetFunctionsBlockDialog::PGetFunctionsBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl)
 {
@@ -56,8 +73,26 @@ PGetFunctionsBlockDialog::PGetFunctionsBlockDialog(const QString helpUrl) : fHel
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Adds a function to the FUNCTIONS block text edit after carrying out some primitve tests about
- * the consistency of the function (far from being a syntax/semantic checker!!).
+ * @brief Validates and adds a function definition to the FUNCTIONS block.
+ *
+ * @details Performs basic syntax validation on the user's input before adding
+ * it to the FUNCTIONS block text area. This is a primitive validation that
+ * checks for common errors but is not a complete syntax/semantic checker.
+ *
+ * @par Validation Steps:
+ * -# Checks that input is not empty
+ * -# Verifies the function starts with "fun" prefix
+ * -# Uses regex to confirm "funX =" format where X is a positive number
+ * -# Ensures no function references appear in the expression (functions cannot
+ *    reference other functions in musrfit)
+ *
+ * @par Error Handling:
+ * If validation fails, an error dialog is displayed describing the problem
+ * and the function is not added. The input field is preserved so the user
+ * can correct the error.
+ *
+ * @note On successful validation, the function is appended to the text display
+ *       and the input field is cleared for the next entry.
  */
 void PGetFunctionsBlockDialog::addFunction()
 {
@@ -101,7 +136,11 @@ void PGetFunctionsBlockDialog::addFunction()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Generates a help content window showing the description of the FUNCTIONS block.
+ * @brief Opens the online help documentation for FUNCTIONS 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 PGetFunctionsBlockDialog::helpContent()
 {

src/musredit_qt6/musredit/PGetFunctionsBlockDialog.h

@@ -27,14 +27,62 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetFunctionsBlockDialog.h
+ * @brief Dialog for creating FUNCTIONS blocks in msr files.
+ * @details This header defines the PGetFunctionsBlockDialog class which provides
+ * a dialog for entering and validating function definitions needed to create a
+ * FUNCTIONS block in a musrfit msr file. Functions allow combining fit parameters
+ * using mathematical expressions.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PGetParameterBlockDialog For creating FITPARAMETER blocks
+ * @see PGetTheoryBlockDialog For creating THEORY blocks
+ */
+
 #ifndef _PGETFUNCTIONSBLOCKDIALOG_H_
 #define _PGETFUNCTIONSBLOCKDIALOG_H_
 
 #include "ui_PGetFunctionsBlockDialog.h"
 
-//-----------------------------------------------------------------------------------
+//---------------------------------------------------------------------------
 /**
- * <p>Handles the content of the FUNCTIONS block dialog.
+ * @class PGetFunctionsBlockDialog
+ * @brief Dialog for creating FUNCTIONS blocks in msr files.
+ *
+ * @details This dialog allows users to define mathematical functions that
+ * combine fit parameters. Functions are used in musrfit to create derived
+ * quantities from the basic fit parameters, enabling complex relationships
+ * between parameters without modifying the theory function.
+ *
+ * @par Function Syntax:
+ * Functions follow the format "funX = expression" where:
+ * - X is a positive integer (function number)
+ * - expression can contain: parN (parameters), mapN (mapped parameters),
+ *   mathematical operators (+, -, *, /), and standard functions (cos, sin, exp, etc.)
+ *
+ * @par Validation Rules:
+ * The dialog performs basic syntax validation:
+ * - Function must start with "fun" prefix
+ * - Function must contain "funX =" format where X is a number
+ * - A function definition cannot reference other functions (no "funN" in expression)
+ *
+ * @par Example Functions:
+ * @code
+ * FUNCTIONS
+ * fun1 = par1 * cos(par2 * 0.017453)
+ * fun2 = par3 + par4
+ * fun3 = map1 * par5
+ * @endcode
+ *
+ * @note The validation is basic and does not perform full syntax/semantic checking.
+ *       Complex expressions should be verified by running musrfit.
+ *
+ * @see PGetParameterBlockDialog For defining fit parameters used in functions
  */
 class PGetFunctionsBlockDialog : public QDialog, private Ui::PGetFunctionsBlockDialog
 {
@@ -43,14 +91,28 @@ class PGetFunctionsBlockDialog : public QDialog, private Ui::PGetFunctionsBlockD
   public:
     PGetFunctionsBlockDialog(const QString helpUrl = "");
 
+    /**
+     * @brief Returns the complete FUNCTIONS block text.
+     * @return All function definitions entered by the user, ready for
+     *         insertion into an msr file.
+     */
     QString getFunctionsBlock() { return fFunctionBlock_plainTextEdit->toPlainText(); }
 
   private slots:
+    /**
+     * @brief Validates and adds a function to the FUNCTIONS block.
+     * @details Performs basic syntax checking before adding the function
+     *          to the text display.
+     */
     void addFunction();
+
+    /**
+     * @brief Opens the online help for FUNCTIONS blocks.
+     */
     void helpContent();
 
   private:
-    QString fHelpUrl; ///< help url address for the FUNCTIONS block.
+    QString fHelpUrl; ///< URL to the online documentation for FUNCTIONS blocks.
 };
 
 #endif // _PGETFUNCTIONSBLOCKDIALOG_H_