diff --git a/src/musredit_qt6/musredit/PGetFunctionsBlockDialog.cpp b/src/musredit_qt6/musredit/PGetFunctionsBlockDialog.cpp index 3c76f09cc..b08cd4a19 100644 --- a/src/musredit_qt6/musredit/PGetFunctionsBlockDialog.cpp +++ b/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 #include #include @@ -41,9 +54,13 @@ //---------------------------------------------------------------------------------------------------- /** - *

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 //---------------------------------------------------------------------------------------------------- /** - *

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() //---------------------------------------------------------------------------------------------------- /** - *

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() { diff --git a/src/musredit_qt6/musredit/PGetFunctionsBlockDialog.h b/src/musredit_qt6/musredit/PGetFunctionsBlockDialog.h index 5b4246137..d530b9242 100644 --- a/src/musredit_qt6/musredit/PGetFunctionsBlockDialog.h +++ b/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" -//----------------------------------------------------------------------------------- +//--------------------------------------------------------------------------- /** - *

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_