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

src/musredit_qt6/musredit/PFindDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PFindDialog.cpp
+ * @brief Implementation of the PFindDialog class.
+ * @details This file implements the find dialog functionality for the musredit
+ * text editor. The dialog allows users to search for text with various options
+ * such as case sensitivity, whole word matching, and search direction.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #include <QPushButton>
 #include <QComboBox>
 #include <QCheckBox>
@@ -37,12 +50,23 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Sets up the find dialog.
+ * @brief Constructs and initializes the find dialog.
  *
- * \param data pointer to the find/replace data structure needed to perform the task.
- * \param selection flag indicating if the find shall be restricted to the selected area
- * \param parent pointer to the parent object
- * \param f qt specific window flags
+ * @details Sets up the find dialog UI and initializes all controls with values
+ * from the provided data structure. The dialog is created as modal.
+ *
+ * The constructor performs the following initialization:
+ * -# Sets up the UI from the .ui file
+ * -# Disables the Find button if no search text is provided
+ * -# Disables the "Selected text" option if no text is selected in the editor
+ * -# Populates all controls with values from the data structure
+ *
+ * @param data Pointer to a PFindReplaceData structure containing initial search
+ *             parameters and receiving the user's selections on dialog close.
+ * @param selection If true, text is currently selected in the editor and the
+ *                  "search in selection" option is enabled; if false, the option
+ *                  is disabled and unchecked.
+ * @param parent Pointer to the parent widget (typically the main editor window).
  */
 PFindDialog::PFindDialog(PFindReplaceData *data, const bool selection, QWidget *parent) :
     QDialog(parent), fData(data)
@@ -75,8 +99,22 @@ PFindDialog::PFindDialog(PFindReplaceData *data, const bool selection, QWidget *
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Extracts all the necessary informations from the find dialog, feeds it to the find/replace
- * structure and returns a point to this structure.
+ * @brief Retrieves the search parameters from the dialog.
+ *
+ * @details Extracts the current values from all dialog controls and updates
+ * the PFindReplaceData structure. This method should be called after the
+ * dialog is accepted to retrieve the user's search settings.
+ *
+ * The following values are extracted:
+ * - findText: The text to search for
+ * - caseSensitive: Whether to match case
+ * - wholeWordsOnly: Whether to match whole words only
+ * - fromCursor: Whether to start search from cursor position
+ * - findBackwards: Whether to search backwards
+ * - selectedText: Whether to search only within selected text (if enabled)
+ *
+ * @return Pointer to the updated PFindReplaceData structure containing
+ *         all search parameters as set by the user.
  */
 PFindReplaceData* PFindDialog::getData()
 {
@@ -93,7 +131,14 @@ PFindReplaceData* PFindDialog::getData()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Enables the find button only if there is any find text entered.
+ * @brief Slot to enable/disable the Find button based on search text availability.
+ *
+ * @details This slot is connected to the text changed signal of the find combo box.
+ * It enables the Find button only when there is text to search for, preventing
+ * empty searches.
+ *
+ * @param text The current text in the combo box (parameter unused; the method
+ *             reads directly from the widget to handle all input scenarios).
  */
 void PFindDialog::onFindTextAvailable(const QString&)
 {

src/musredit_qt6/musredit/PFindDialog.h

@@ -27,6 +27,22 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PFindDialog.h
+ * @brief Find dialog for text searching in musredit.
+ * @details This header defines the PFindDialog class which provides a dialog
+ * for searching text within msr files. The dialog supports various search
+ * options including case sensitivity, whole word matching, and search direction.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ * @copyright Copyright (C) 2010-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PReplaceDialog For find and replace functionality
+ * @see PFindReplaceData For the data structure used by this dialog
+ */
+
 #ifndef _PFINDDIALOG_H_
 #define _PFINDDIALOG_H_
 
@@ -35,7 +51,39 @@
 
 //--------------------------------------------------------------------------------------------------
 /**
- * <p>PFindDialog is the class handling the find dialog.
+ * @class PFindDialog
+ * @brief Dialog for searching text in the editor.
+ *
+ * @details This class implements a modal dialog that allows users to search for
+ * text within the current msr file. The dialog provides various search options
+ * and stores the search parameters in a PFindReplaceData structure.
+ *
+ * @par Search Options:
+ * - Case sensitive matching
+ * - Whole words only matching
+ * - Search from cursor position or document start
+ * - Forward or backward search direction
+ * - Search within selected text only (when text is selected)
+ *
+ * @par UI Elements:
+ * The dialog UI is defined in PFindDialog.ui and includes:
+ * - A combo box (fFind_comboBox) for entering and selecting search text
+ * - Checkboxes for search options
+ * - Find and Cancel buttons
+ *
+ * @par Usage:
+ * @code
+ * PFindReplaceData data;
+ * data.findText = "searchterm";
+ * PFindDialog dialog(&data, hasSelection, this);
+ * if (dialog.exec() == QDialog::Accepted) {
+ *     PFindReplaceData *result = dialog.getData();
+ *     // Perform search with result->findText
+ * }
+ * @endcode
+ *
+ * @see PReplaceDialog For combined find and replace functionality
+ * @see PFindReplaceData For the structure storing search parameters
  */
 class PFindDialog : public QDialog, private Ui::PFindDialog
 {
@@ -43,15 +91,23 @@ class PFindDialog : public QDialog, private Ui::PFindDialog
 
   public:
     PFindDialog(PFindReplaceData *data, const bool selection, QWidget *parent = nullptr);
+
+    /**
+     * @brief Virtual destructor.
+     */
     virtual ~PFindDialog() {}
 
     virtual PFindReplaceData *getData();
 
   protected slots:
-    virtual void onFindTextAvailable(const QString&);
+    /**
+     * @brief Slot called when the find text changes.
+     * @param text The current text in the find combo box (unused, reads from widget directly).
+     */
+    virtual void onFindTextAvailable(const QString& text);
 
   private:
-    PFindReplaceData *fData; ///< stores the data necessary to perform find/replace.
+    PFindReplaceData *fData; ///< Pointer to the find/replace data structure for storing search parameters.
 };
 
 #endif // _PFINDDIALOG_H_