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

src/musredit_qt6/musredit/PGetTheoryBlockDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetTheoryBlockDialog.cpp
+ * @brief Implementation of the THEORY block dialog for musredit.
+ *
+ * @details Provides the implementation of PGetTheoryBlockDialog class methods
+ * for creating and editing THEORY blocks in musrfit msr files. The dialog
+ * enables interactive selection and combination of theory functions with
+ * visual LaTeX equation previews.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ */
+
 #include <QMessageBox>
 #include <QTextEdit>
 #include <QComboBox>
@@ -41,10 +54,32 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructor - Initializes the THEORY block dialog.
  *
- * \param admin pointer to the administration class object needed to extract the default theory set informations.
+ * @details Sets up the user interface and populates the theory function combo box
- * \param helpUrl help url for the asymmetry run block
+ * with all available theory functions from the administration object. Each function
+ * is displayed with its label and, if available, a LaTeX-rendered equation icon.
+ *
+ * The combo box icon size is set to 250x20 pixels to accommodate LaTeX equation
+ * images. Icons are loaded from embedded Qt resources (:/latex_images/) based on
+ * the pixmap name specified in each theory function definition.
+ *
+ * The dialog is configured as modal, requiring user interaction before returning
+ * control to the parent window.
+ *
+ * @param admin Pointer to the PAdmin administration object containing theory
+ *              function definitions loaded from musrfit_startup.xml. Must not be
+ *              nullptr for proper operation.
+ * @param helpUrl URL string for the online help documentation. If empty, help
+ *                button will display a placeholder message instead of opening a
+ *                web browser.
+ *
+ * @note The dialog assumes fAdmin is valid and contains at least one theory function.
+ *       No validation is performed on the admin pointer.
+ *
+ * @see PAdmin::getTheoryCounts() Returns the number of available theory functions
+ * @see PAdmin::getTheoryItem() Retrieves a specific theory function definition
+ * @see PTheory Structure containing function name, parameters, label, and pixmap name
  */
 PGetTheoryBlockDialog::PGetTheoryBlockDialog(PAdmin *admin, const QString helpUrl) :
               fAdmin(admin),
@@ -73,7 +108,39 @@ PGetTheoryBlockDialog::PGetTheoryBlockDialog(PAdmin *admin, const QString helpUr
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the theory function string of the currently selected theory function.
+ * @brief Generates the formatted theory function string for the selected function.
+ *
+ * @details Constructs a complete theory function line suitable for insertion into
+ * an msr file THEORY block. The format depends on the function type:
+ *
+ * For standard functions:
+ * @code
+ * functionName   1   2   3   ...   (comment)
+ * @endcode
+ *
+ * For user-defined functions (userFcn):
+ * @code
+ * userFcn   libMyLibrary.so  TMyFunction  1   2   ...   (comment)
+ * @endcode
+ *
+ * The parameter numbers (1, 2, 3, ...) are placeholders that should be replaced
+ * with actual FITPARAMETER indices or map references before the msr file is used
+ * for fitting.
+ *
+ * @return QString containing the formatted theory function line with:
+ *         - Function name
+ *         - Library and function names (for userFcn only)
+ *         - Sequential parameter placeholders (1 to params count)
+ *         - Parameter comment from theory definition
+ *         Returns "????" if the theory item cannot be retrieved (invalid index).
+ *
+ * @note This is a private slot method typically called by addPlus() and addMultiply().
+ *
+ * @see PTheory::name Function name as defined in XML
+ * @see PTheory::params Number of parameters required by the function
+ * @see PTheory::comment Descriptive text explaining the parameters
+ * @see addPlus() Uses this method to add functions with addition
+ * @see addMultiply() Uses this method to add functions with multiplication
  */
 QString PGetTheoryBlockDialog::getTheoFuncString()
 {
@@ -100,7 +167,27 @@ QString PGetTheoryBlockDialog::getTheoFuncString()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>adds the current theory function to the text field and additionally adds a '+'.
+ * @brief Adds the current theory function followed by a '+' operator.
+ *
+ * @details Retrieves the formatted string for the currently selected theory
+ * function and appends it to the theory block text editor, followed by a newline
+ * and a '+' character. The '+' indicates that the next function should be added
+ * (summed) rather than multiplied with the current function.
+ *
+ * This creates additive terms in the fit model. For example:
+ * @code
+ * asymmetry   1
+ * simpleGss   2   (rate)
+ * +
+ * asymmetry   3
+ * simpleLor   4   (rate)
+ * @endcode
+ * Represents: A1*Gss(t) + A2*Lor(t)
+ *
+ * @note This slot is connected to the "Plus" button in the UI (fPlus_pushButton).
+ *
+ * @see getTheoFuncString() Generates the theory function string
+ * @see addMultiply() For multiplicative combination of functions
  */
 void PGetTheoryBlockDialog::addPlus()
 {
@@ -110,7 +197,27 @@ void PGetTheoryBlockDialog::addPlus()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>adds the current theory function to the text field (newline == '*').
+ * @brief Adds the current theory function for multiplication.
+ *
+ * @details Retrieves the formatted string for the currently selected theory
+ * function and appends it to the theory block text editor on a new line. In
+ * musrfit theory block syntax, functions on consecutive lines (without a '+'
+ * separator between them) are implicitly multiplied together.
+ *
+ * This creates multiplicative terms in the fit model. For example:
+ * @code
+ * asymmetry   1
+ * simpleGss   2   (rate)
+ * TFieldCos   3   4   (phase frequency)
+ * @endcode
+ * Represents: A1 * Gss(t) * cos(ωt + φ)
+ *
+ * @note In the code comment "newline == '*'" refers to the implicit multiplication
+ *       semantics: a newline without '+' means multiply.
+ * @note This slot is connected to the "Multiply" button in the UI (fMultiply_pushButton).
+ *
+ * @see getTheoFuncString() Generates the theory function string
+ * @see addPlus() For additive combination of functions
  */
 void PGetTheoryBlockDialog::addMultiply()
 {
@@ -120,7 +227,25 @@ void PGetTheoryBlockDialog::addMultiply()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Generates a help content window showing the description of the theory block.
+ * @brief Opens online help documentation for THEORY blocks.
+ *
+ * @details Attempts to open the help URL in the user's default web browser using
+ * QDesktopServices::openUrl(). The help typically provides comprehensive
+ * documentation on:
+ * - Available theory functions and their physical meanings
+ * - Parameter descriptions for each function
+ * - Syntax rules for combining functions
+ * - Examples of common theory block patterns for µSR data analysis
+ *
+ * Error handling:
+ * - If fHelpUrl is empty: displays an information dialog with a placeholder message
+ * - If the browser fails to open: displays a critical error dialog with the URL
+ *   formatted as a clickable hyperlink for manual access
+ *
+ * @note The URL is parsed in TolerantMode to handle various URL formats gracefully.
+ * @note This slot is connected to the help button in the UI.
+ *
+ * @see PGetTheoryBlockDialog::PGetTheoryBlockDialog() Where fHelpUrl is initialized
  */
 void PGetTheoryBlockDialog::helpContent()
 {

src/musredit_qt6/musredit/PGetTheoryBlockDialog.h

@@ -27,34 +27,192 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetTheoryBlockDialog.h
+ * @brief Dialog for creating THEORY blocks in msr files.
+ * @details This header defines the PGetTheoryBlockDialog class which provides
+ * a dialog for building theory function expressions needed to create a THEORY
+ * block in a musrfit msr file. The dialog presents available theory functions
+ * with LaTeX-rendered equation previews.
+ *
+ * @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 PGetFunctionsBlockDialog For creating FUNCTIONS blocks
+ * @see PAdmin For theory function definitions loaded from XML
+ */
+
 #ifndef _PGETTHEORYBLOCKDIALOG_H_
 #define _PGETTHEORYBLOCKDIALOG_H_
 
 #include "PAdmin.h"
 #include "ui_PGetTheoryBlockDialog.h"
 
-//-----------------------------------------------------------------------------
+//---------------------------------------------------------------------------
 /**
- * <p>Class handling the content of the menu: Edit/Add Block/Theory Block.
+ * @class PGetTheoryBlockDialog
+ * @brief Dialog for creating THEORY blocks in msr files.
+ *
+ * @details This dialog allows users to build theory function expressions by
+ * selecting from a list of available theory functions. Functions can be
+ * combined using addition (+) or multiplication (*) operators. The dialog
+ * displays LaTeX-rendered equation icons for visual function identification.
+ *
+ * @par Available Theory Functions:
+ * Theory functions are loaded from the XML configuration file and include:
+ * - Asymmetry functions (asymmetry, simpleGss, simpleLor, etc.)
+ * - Relaxation functions (expLF, stretchedExp, etc.)
+ * - Oscillation functions (TFieldCos, internFld, etc.)
+ * - User-defined functions (userFcn)
+ *
+ * @par Theory Block Syntax:
+ * Functions on the same line are multiplied; functions preceded by '+' are added:
+ * @code
+ * THEORY
+ * asymmetry   1
+ * simpleGss   2   (rate)
+ * +
+ * asymmetry   3
+ * simpleLor   4   (rate)
+ * @endcode
+ * This represents: A1 * Gss(t) + A2 * Lor(t)
+ *
+ * @par Parameter Numbering:
+ * Each function line includes placeholder parameter numbers (1, 2, 3...) that
+ * should be replaced with actual parameter references from the FITPARAMETER
+ * block or map indices.
+ *
+ * @see PAdmin For loading and managing theory function definitions
+ * @see PTheory For the structure holding individual theory function data
  */
 class PGetTheoryBlockDialog : public QDialog, private Ui::PGetTheoryBlockDialog
 {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Constructs a dialog for creating THEORY blocks.
+     *
+     * @details Initializes the dialog with available theory functions from the
+     * administration object. Sets up the combo box with function names and
+     * LaTeX equation icons loaded from embedded resources. The dialog is
+     * configured as modal to ensure user interaction completion.
+     *
+     * @param admin Pointer to the PAdmin object containing theory function
+     *              definitions loaded from the XML configuration file. If nullptr,
+     *              the dialog will not function properly.
+     * @param helpUrl URL string pointing to online documentation for THEORY blocks.
+     *                If empty, help button will show a placeholder message.
+     *
+     * @see PAdmin::getTheoryCounts() For retrieving number of available functions
+     * @see PAdmin::getTheoryItem() For accessing individual theory function data
+     */
     PGetTheoryBlockDialog(PAdmin *admin = 0, const QString helpUrl = "");
 
+    /**
+     * @brief Returns the complete theory block text.
+     *
+     * @details Retrieves all theory function expressions entered by the user
+     * through the dialog interface. The returned string is formatted according
+     * to musrfit msr file specifications and is ready for direct insertion into
+     * the THEORY section of an msr file.
+     *
+     * @return QString containing all theory function lines, with proper formatting
+     *         including function names, parameter placeholders, comments, and
+     *         operators ('+' for addition, newline for multiplication).
+     *
+     * @note The returned string should be parsed and parameter numbers replaced
+     *       with actual FITPARAMETER references before saving to file.
+     */
     QString getTheoryBlock() { return fTheoryBlock_plainTextEdit->toPlainText(); }
 
   private slots:
+    /**
+     * @brief Generates the theory function string for the selected function.
+     *
+     * @details Constructs a formatted string for the currently selected theory
+     * function from the combo box. The string includes:
+     * - Function name (e.g., "asymmetry", "simpleGss")
+     * - For userFcn: library and function names (e.g., "libMyLibrary.so TMyFunction")
+     * - Sequential parameter placeholders (1, 2, 3, ...)
+     * - Function comment describing parameters
+     *
+     * Example output: "simpleGss   1   2   (phase frequency)"
+     *
+     * @return QString containing the formatted theory function line. Returns "????"
+     *         if no valid theory item is found at the current index.
+     *
+     * @see PTheory For the structure defining theory function properties
+     */
     QString getTheoFuncString();
+
+    /**
+     * @brief Adds the selected function followed by a '+' operator.
+     *
+     * @details Appends the currently selected theory function to the text editor,
+     * followed by a '+' character on a new line. This indicates that the next
+     * function should be added (summed) rather than multiplied. In musrfit
+     * theory blocks, the '+' operator creates additive terms in the fit function.
+     *
+     * Example result in editor:
+     * @code
+     * asymmetry   1
+     * simpleGss   2   (rate)
+     * +
+     * @endcode
+     *
+     * @note Connected to the "Plus" button click signal in the UI.
+     *
+     * @see addMultiply() For multiplicative combination
+     */
     void addPlus();
+
+    /**
+     * @brief Adds the selected function (multiplication with next line).
+     *
+     * @details Appends the currently selected theory function to the text editor
+     * on a new line. In musrfit theory blocks, functions on consecutive lines
+     * (without a '+' separator) are multiplied together. This is the default
+     * operation for combining functions like asymmetry with relaxation.
+     *
+     * Example result in editor:
+     * @code
+     * asymmetry   1
+     * simpleGss   2   (rate)
+     * @endcode
+     * Represents: A1 * Gss(t)
+     *
+     * @note Connected to the "Multiply" button click signal in the UI.
+     *
+     * @see addPlus() For additive combination
+     */
     void addMultiply();
+
+    /**
+     * @brief Opens the online help for THEORY blocks.
+     *
+     * @details Attempts to open the help URL in the system's default web browser
+     * using QDesktopServices. If the URL is empty, displays a placeholder
+     * information message. If the browser cannot be opened, shows an error
+     * dialog with the URL for manual access.
+     *
+     * The help documentation typically covers:
+     * - Available theory functions and their parameters
+     * - Syntax for combining functions
+     * - Examples of common theory block patterns
+     *
+     * @note Connected to the help button click signal in the UI.
+     *
+     * @see PGetTheoryBlockDialog::PGetTheoryBlockDialog() Where helpUrl is set
+     */
     void helpContent();
 
   private:
-    PAdmin *fAdmin;   ///< pointer to the administration class object needed to extract the default theory set informations.
+    PAdmin *fAdmin;   ///< Pointer to the administration object for accessing theory function definitions.
-    QString fHelpUrl; ///< help url for the asymmetry run block
+    QString fHelpUrl; ///< URL to the online documentation for THEORY blocks.
 };
 
 #endif // _PGETTHEORYBLOCKDIALOG_H_