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

src/musredit_qt6/mupp/PVarDialog.cpp

@@ -41,8 +41,13 @@
 
 //--------------------------------------------------------------------------
 /**
- * @brief PShowVarNameDialog::PShowVarNameDialog. Ctor
+ * @brief Constructor for PShowVarNameDialog.
- * @param info containing the necessary information of the collection
+ *
+ * Creates a dialog displaying all variable names from a collection. If the
+ * collection name contains a path, only the filename portion is displayed.
+ * Each variable is shown with its index number.
+ *
+ * @param info reference to PCollInfo structure containing the collection name and variable names
  */
 PShowVarNameDialog::PShowVarNameDialog(PCollInfo &info)
 {
@@ -85,12 +90,25 @@ PShowVarNameDialog::PShowVarNameDialog(PCollInfo &info)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::PVarDialog. Variable GUI allowing the users to define
+ * @brief Constructor for PVarDialog.
- * variables.
+ *
- * @param collection_list list of all the collections
+ * Creates a variable definition dialog with a text editor for variable expressions
- * @param darkTheme plain/dark theme flag
+ * and a collection list view. The dialog allows users to define custom variables
- * @param parent parent widget pointer
+ * using expressions that reference collection variables as identifiers (prefixed
- * @param f window flag
+ * with '$'). Multiple collections can be selected, and the dialog validates that
+ * all identifiers exist in the selected collections.
+ *
+ * The dialog includes buttons for:
+ * - Check: validates variable definitions
+ * - Add: adds variables to the mupp GUI
+ * - Help: displays syntax information
+ * - ShowVarName: displays variable names from selected collection
+ * - Cancel: closes the dialog
+ *
+ * @param collection_list vector of all available collections with their variable names
+ * @param darkTheme if true, uses dark theme icons; if false, uses plain icons
+ * @param parent optional parent widget pointer
+ * @param f optional window flags for the dialog
  */
 PVarDialog::PVarDialog(QVector<PCollInfo> collection_list, bool darkTheme,
                        QWidget *parent, Qt::WindowFlags f) :
@@ -166,7 +184,12 @@ PVarDialog::PVarDialog(QVector<PCollInfo> collection_list, bool darkTheme,
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::check. Allows the user to check the variable string.
+ * @brief Validates variable definitions and emits check_request signal.
+ *
+ * Performs basic checks (syntax, presence of 'var' keyword, error variable
+ * definitions) and consistency checks (identifiers exist in collections).
+ * If validation succeeds, emits the check_request signal with the variable
+ * string and selected collection indices.
  */
 void PVarDialog::check()
 {
@@ -187,7 +210,12 @@ void PVarDialog::check()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::add. It is used to initiate the add variable to the mupp GUI.
+ * @brief Validates and adds variable definitions to the mupp GUI.
+ *
+ * Checks that input is present and at least one collection is selected.
+ * Performs basic checks and consistency validation. If all checks pass,
+ * emits the add_request signal with the variable string and selected
+ * collection indices.
  */
 void PVarDialog::add()
 {
@@ -218,7 +246,13 @@ void PVarDialog::add()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::help
+ * @brief Displays help information about variable definition syntax.
+ *
+ * Shows a message box explaining the syntax for defining variables:
+ * - Basic syntax: var <var_name> = <expr>
+ * - Identifiers are prefixed with '$' (e.g., $sigma)
+ * - Expressions can use standard mathematical functions
+ * - Example: var sigSC = pow(abs(pow($sigma,2.0)-pow(0.11,2.0)),0.5)
  */
 void PVarDialog::help()
 {
@@ -233,8 +267,12 @@ void PVarDialog::help()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::showVarNames. Show a variable name dialog for a given
+ * @brief Displays variable names from the selected collection.
- * selected collection.
+ *
+ * Shows a PShowVarNameDialog containing all variable names from the currently
+ * selected collection. Only one collection can be displayed at a time.
+ * Displays error messages if no collection is selected, multiple collections
+ * are selected, or if an invalid collection index is encountered.
  */
 void PVarDialog::showVarNames()
 {
@@ -262,9 +300,16 @@ void PVarDialog::showVarNames()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::basic_check. Carry out basic checks before feeding it
+ * @brief Performs basic validation checks on variable definitions.
- * to the parser.
+ *
- * @return true on success
+ * Validates the following:
+ * - Input is not empty
+ * - At least one collection is selected
+ * - At least one 'var' definition is present
+ * - Each 'var' keyword is followed by a variable name
+ * - For each variable, a corresponding error variable (with 'Err' suffix) exists
+ *
+ * @return true if all basic checks pass, false otherwise (with error message displayed)
  */
 bool PVarDialog::basic_check()
 {
@@ -313,10 +358,17 @@ bool PVarDialog::basic_check()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::var_consistency_check. Variable consistency checks. For
+ * @brief Validates that all identifiers exist in selected collections.
- * instance it is checked that for each variable there is also the corresponding
+ *
- * error variable defined.
+ * Collects all identifiers (prefixed with '$') and variable names from the
- * @return true on success
+ * variable definition string. For each identifier, checks that it either:
+ * 1. Is a variable being defined in the current definition string, or
+ * 2. Exists as a variable in one of the selected collections
+ *
+ * Handles both regular identifiers and error identifiers (ending with 'Err').
+ * Displays error message if any identifier is not found in selected collections.
+ *
+ * @return true if all identifiers are valid, false otherwise (with error message displayed)
  */
 bool PVarDialog::var_consistency_check()
 {
@@ -404,10 +456,15 @@ bool PVarDialog::var_consistency_check()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::collectVarNames. Collect variable names from edit variable.
+ * @brief Collects all variable names from a tokenized string list.
- * @param list input list
+ *
- * @param ok true if ok
+ * Scans the input list for 'var' keywords and extracts the following token
- * @return return variable list
+ * as the variable name. Sets the ok flag to false if a 'var' keyword is
+ * found at the end of the list without a following variable name.
+ *
+ * @param list reference to a tokenized string list containing variable definitions
+ * @param ok reference to boolean flag; set to true if all 'var' keywords have associated names, false otherwise
+ * @return QStringList containing all collected variable names
  */
 QStringList PVarDialog::collectVarNames(QStringList &list, bool &ok)
 {
@@ -430,10 +487,16 @@ QStringList PVarDialog::collectVarNames(QStringList &list, bool &ok)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PVarDialog::hasErrorDef. Check for error definition
+ * @brief Checks that each variable has a corresponding error definition.
- * @param varNames variable name list
+ *
- * @param name failed variable name
+ * For every variable name in the list that doesn't contain 'Err', checks
- * @return true on success
+ * that a corresponding variable with an 'Err' suffix exists in the list.
+ * If any variable lacks its error counterpart, the variable name is stored
+ * in the name parameter.
+ *
+ * @param varNames reference to a list of variable names to validate
+ * @param name reference to QString that will hold the name of the first variable without an error definition
+ * @return true if all non-error variables have corresponding error definitions, false otherwise
  */
 bool PVarDialog::hasErrorDef(QStringList &varNames, QString &name)
 {

src/musredit_qt6/mupp/PVarDialog.h

@@ -40,64 +40,151 @@
 
 //-----------------------------------------------------------------------------
 /**
- * @brief The PCollInfo struct
+ * @brief The PCollInfo struct holds collection information.
+ *
+ * This structure stores the name of a collection and a list of all variable
+ * names contained within that collection. It is used to pass collection
+ * metadata to various dialogs and functions.
  */
 struct PCollInfo
 {
-  QString fCollName; ///< collection name
+  QString fCollName;    ///< collection name (may include path)
   QStringList fVarName; ///< variable names of the given collection
 };
 
 //-----------------------------------------------------------------------------
 /**
- * @brief The PShowVarNameDialog class. Class used to create a show variable
+ * @brief The PShowVarNameDialog class displays variable names from a collection.
- * name dialog.
+ *
+ * This dialog shows all variable names contained in a selected collection,
+ * displaying them as an indexed list. It provides a simple interface for
+ * users to browse through available variables in a collection.
  */
 class PShowVarNameDialog : public QDialog
 {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Constructor for PShowVarNameDialog.
+     * @param info reference to a PCollInfo structure containing the collection name and variable names to display
+     */
     PShowVarNameDialog(PCollInfo &info);
 };
 
 //-----------------------------------------------------------------------------
 /**
- * @brief The PVarDialog class
+ * @brief The PVarDialog class provides a GUI for defining custom variables.
+ *
+ * This dialog allows users to define custom variables based on existing
+ * variables from selected collections. Variables are defined using expressions
+ * that can reference collection variables as identifiers (prefixed with '$').
+ * The dialog validates that both a variable and its corresponding error variable
+ * (suffixed with 'Err') are defined, and checks that all identifiers exist in
+ * the selected collections.
+ *
+ * Example variable definition:
+ * @code
+ * var sigSC = pow(abs(pow($sigma,2.0)-pow(0.11,2.0)),0.5)
+ * var sigSCErr = <error_expression>
+ * @endcode
  */
 class PVarDialog : public QDialog
 {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Constructor for PVarDialog.
+     * @param collection_list vector of PCollInfo structures containing all available collections
+     * @param darkTheme flag indicating whether to use dark theme icons (true) or plain icons (false)
+     * @param parent optional parent widget pointer
+     * @param f optional window flags for the dialog
+     */
     PVarDialog(QVector<PCollInfo> collection_list, bool darkTheme,
                QWidget *parent = nullptr,
                Qt::WindowFlags f = Qt::WindowFlags());
 
   private:
-    std::unique_ptr<QPlainTextEdit> fVarEdit;
+    std::unique_ptr<QPlainTextEdit> fVarEdit;      ///< text editor for variable definitions
-    std::unique_ptr<QListWidget> fCollectionView;
+    std::unique_ptr<QListWidget> fCollectionView;  ///< list widget displaying available collections
-    std::unique_ptr<QPushButton> fCancel;
+    std::unique_ptr<QPushButton> fCancel;          ///< cancel button to reject the dialog
-    std::unique_ptr<QPushButton> fAdd;
+    std::unique_ptr<QPushButton> fAdd;             ///< add button to add variables to mupp GUI
-    std::unique_ptr<QPushButton> fCheck;
+    std::unique_ptr<QPushButton> fCheck;           ///< check button to validate variable definitions
-    std::unique_ptr<QPushButton> fHelp;
+    std::unique_ptr<QPushButton> fHelp;            ///< help button to display syntax information
-    std::unique_ptr<QPushButton> fShowVarName;
+    std::unique_ptr<QPushButton> fShowVarName;     ///< button to show variable names from selected collection
 
-    QVector<PCollInfo> fCollList;
+    QVector<PCollInfo> fCollList; ///< vector holding all collection information
 
+    /**
+     * @brief Performs basic validation checks on variable definitions.
+     * @return true if basic checks pass, false otherwise
+     */
     bool basic_check();
+
+    /**
+     * @brief Validates that all identifiers exist in selected collections.
+     *
+     * Checks that every identifier (prefixed with '$') used in the variable
+     * definitions exists either as a variable being defined or as a variable
+     * in one of the selected collections.
+     * @return true if all identifiers are valid, false otherwise
+     */
     bool var_consistency_check();
+
+    /**
+     * @brief Collects all variable names from a tokenized string list.
+     * @param list reference to a tokenized string list containing variable definitions
+     * @param ok reference to a boolean flag indicating success or failure
+     * @return QStringList containing all collected variable names
+     */
     QStringList collectVarNames(QStringList &list, bool& ok);
+
+    /**
+     * @brief Checks that each variable has a corresponding error definition.
+     *
+     * For every variable name that doesn't end with 'Err', checks that a
+     * corresponding variable with 'Err' suffix exists.
+     * @param varNames reference to a list of variable names to check
+     * @param name reference to QString that will hold the name of the first variable without an error definition
+     * @return true if all variables have error definitions, false otherwise
+     */
     bool hasErrorDef(QStringList &varNames, QString& name);
 
   private slots:
+    /**
+     * @brief Slot to validate variable definitions and emit check_request signal.
+     */
     void check();
+
+    /**
+     * @brief Slot to validate and add variable definitions, emitting add_request signal.
+     */
     void add();
+
+    /**
+     * @brief Slot to display help information about variable syntax.
+     */
     void help();
+
+    /**
+     * @brief Slot to show a dialog displaying variable names from the selected collection.
+     */
     void showVarNames();
 
   signals:
+    /**
+     * @brief Signal emitted when user requests to check variable definitions.
+     * @param varStr the complete variable definition string from the text editor
+     * @param idx vector of indices indicating which collections are selected
+     */
     void check_request(QString varStr, QVector<int> idx);
+
+    /**
+     * @brief Signal emitted when user requests to add variable definitions.
+     * @param varStr the complete variable definition string from the text editor
+     * @param idx vector of indices indicating which collections are selected
+     */
     void add_request(QString varStr, QVector<int> idx);
 };