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

src/musredit_qt6/musredit/PReplaceConfirmationDialog.cpp

@@ -27,14 +27,98 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PReplaceConfirmationDialog.cpp
+ * @brief Implementation of the find-and-replace confirmation dialog.
+ *
+ * @details Provides the implementation of the PReplaceConfirmationDialog
+ * class which handles user confirmation for individual replacements during
+ * interactive find-and-replace operations in musredit. The dialog provides
+ * a simple, focused interface for making replacement decisions.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ */
+
 #include "PReplaceConfirmationDialog.h"
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructor - Initializes the replace confirmation dialog.
  *
- * \param parent pointer to the parent object
- * \param f qt windows flags
+ * @details Sets up a simple, focused dialog for confirming individual
+ * replacements during interactive find-and-replace operations. The
+ * initialization is minimal, establishing only the essential dialog
+ * configuration for user interaction.
+ *
+ * **Initialization Process:**
+ *
+ * 1. **Base Class Initialization**: Calls QDialog constructor with parent
+ *    widget to establish proper parent-child relationship
+ *
+ * 2. **UI Setup**: Loads the dialog layout, labels, and buttons from the
+ *    Qt Designer UI file via setupUi(). The UI file defines:
+ *    - Dialog title and dimensions
+ *    - Confirmation message text
+ *    - Action buttons (Replace, Skip, Replace All, Cancel, etc.)
+ *    - Button layout and spacing
+ *    - Keyboard shortcuts for quick access
+ *
+ * 3. **Modal Configuration**: Sets the dialog as modal using setModal(true),
+ *    ensuring that:
+ *    - The dialog blocks interaction with the main editor
+ *    - User must make an explicit decision
+ *    - No other editor operations can occur until dialog is closed
+ *    - Focus remains on the dialog until user responds
+ *
+ * **Dialog Workflow:**
+ *
+ * After construction, the typical usage pattern is:
+ * 1. Caller creates dialog instance (this constructor executes)
+ * 2. Caller updates dialog text to show current match context (optional)
+ * 3. Caller invokes exec() to display dialog and wait for user response
+ * 4. User clicks a button (Replace, Skip, Replace All, Cancel)
+ * 5. Dialog returns with appropriate QDialog result code
+ * 6. Caller interprets result and takes appropriate action
+ * 7. Process repeats for next match or terminates
+ *
+ * **Button Actions (typical configuration):**
+ * - **Replace button**: Returns QDialog::Accepted, triggers replacement
+ * - **Skip button**: Returns custom code, advances without replacing
+ * - **Replace All**: Returns custom code, batch replaces remaining matches
+ * - **Cancel button**: Returns QDialog::Rejected, aborts operation
+ *
+ * **Modal Behavior Benefits:**
+ * - Prevents accidental document edits during confirmation
+ * - Maintains clear workflow state
+ * - Ensures user attention on decision
+ * - Simplifies state management in calling code
+ *
+ * @param parent Pointer to the parent widget, typically the main musredit
+ *               editor window. The parent relationship provides:
+ *               - Automatic dialog centering over parent window
+ *               - Consistent visual style and theme
+ *               - Automatic cleanup when parent is destroyed
+ *               - Proper z-order (dialog appears on top of parent)
+ *
+ *               If nullptr, the dialog has no parent and will not center
+ *               over any specific window, though it will still be modal
+ *               with respect to the application.
+ *
+ * @note The dialog is created but not displayed by the constructor. Use
+ *       exec() or show() to make it visible to the user.
+ * @note The actual button configuration and return codes are determined by
+ *       the UI file design and any signal-slot connections established there.
+ * @note Modal dialogs entered via exec() run their own event loop, blocking
+ *       the calling code until the dialog closes.
+ * @note The simple constructor design (no parameters for search/replace text)
+ *       suggests the dialog may be updated after construction but before
+ *       display, or that it shows generic confirmation text.
+ *
+ * @see exec() Qt method to display the dialog modally and return user choice
+ * @see setModal() Qt method that configures modal behavior (called here)
+ * @see setupUi() Qt Designer generated method that constructs the UI
+ * @see QDialog For base class documentation on dialog behavior and return codes
  */
 PReplaceConfirmationDialog::PReplaceConfirmationDialog(QWidget *parent) : QDialog(parent)
 {

src/musredit_qt6/musredit/PReplaceConfirmationDialog.h

@@ -27,6 +27,25 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PReplaceConfirmationDialog.h
+ * @brief Confirmation dialog for find-and-replace operations in musredit.
+ *
+ * @details This header defines the PReplaceConfirmationDialog class which
+ * provides a user confirmation dialog for search-and-replace operations in
+ * the musredit text editor. The dialog allows users to confirm, skip, or
+ * control individual replacements during interactive find-and-replace
+ * sessions.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ * @copyright Copyright (C) 2010-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see musredit Main editor application with find-and-replace functionality
+ * @see PFindDialog For the find/replace search dialog
+ */
+
 #ifndef _PREPLACECONFIRMATIONDIALOG_H_
 #define _PREPLACECONFIRMATIONDIALOG_H_
 
@@ -35,12 +54,103 @@
 
 #include "ui_PReplaceConfirmationDialog.h"
 
+/**
+ * @class PReplaceConfirmationDialog
+ * @brief Confirmation dialog for interactive find-and-replace operations.
+ *
+ * @details This dialog provides user control over individual replacement
+ * operations during interactive find-and-replace sessions in musredit. When
+ * the user performs a "Replace" (as opposed to "Replace All") operation, this
+ * dialog appears for each match, allowing fine-grained control over which
+ * instances should be replaced.
+ *
+ * @par Dialog Purpose:
+ * The dialog serves as an interactive confirmation mechanism that prevents
+ * unintended replacements by giving users the opportunity to review each
+ * match before replacement occurs.
+ *
+ * @par Typical User Actions:
+ * The dialog typically provides several options (exact buttons defined in UI):
+ * - **Replace**: Confirm this replacement and move to next match
+ * - **Skip**: Leave this match unchanged and move to next match
+ * - **Replace All**: Replace this and all remaining matches without further confirmation
+ * - **Cancel/Close**: Abort the replace operation entirely
+ *
+ * @par Usage Context:
+ * This dialog is invoked during interactive find-and-replace workflows:
+ * 1. User opens Find/Replace dialog (Edit → Find/Replace)
+ * 2. User enters search term and replacement text
+ * 3. User clicks "Replace" button (not "Replace All")
+ * 4. Editor finds first match and shows context
+ * 5. This confirmation dialog appears
+ * 6. User makes decision (replace/skip/etc.)
+ * 7. Process repeats for next match until completion or cancellation
+ *
+ * @par Dialog Behavior:
+ * - Modal: Blocks interaction with main editor until decision is made
+ * - Non-resizable: Fixed size appropriate for decision buttons
+ * - Centered over parent: Appears centered on the editor window
+ * - Quick keyboard access: Buttons typically have keyboard shortcuts
+ *
+ * @par Integration:
+ * The dialog integrates with musredit's find-and-replace engine, which:
+ * - Highlights the current match in the editor
+ * - Manages the search state across multiple matches
+ * - Executes the replacement based on user choice
+ * - Advances to the next match after each decision
+ *
+ * @note The dialog is modal, requiring explicit user action before continuing.
+ * @note Return values (via exec()) indicate the user's choice for action.
+ * @note The actual button configuration and return values are defined in the
+ *       UI file and handled by the calling find-and-replace code.
+ *
+ * @see musredit For the main text editor with find-and-replace functionality
+ * @see PFindDialog For the primary find/replace dialog interface
+ */
 class PReplaceConfirmationDialog : public QDialog, public Ui::PReplaceConfirmationDialog
 {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Constructs the replace confirmation dialog.
+     *
+     * @details Initializes the dialog with a simple confirmation interface
+     * for find-and-replace operations. The dialog is configured as modal to
+     * ensure users make an explicit decision before continuing with the
+     * replacement process.
+     *
+     * The constructor sets up the UI from the Qt Designer UI file and
+     * configures basic dialog properties. The actual button configuration,
+     * labels, and layout are defined in the UI file.
+     *
+     * @param parent Pointer to the parent widget (typically the main editor
+     *               window). If nullptr, the dialog has no parent. The
+     *               parent-child relationship ensures:
+     *               - Proper dialog centering over the parent window
+     *               - Automatic cleanup when parent is destroyed
+     *               - Consistent styling and theme inheritance
+     *
+     * @note The dialog is created but not shown by the constructor. The
+     *       caller must invoke exec() to display it modally.
+     * @note Parent ownership is recommended to ensure proper cleanup and
+     *       visual integration with the main application.
+     *
+     * @see exec() Qt method to display the dialog and wait for user response
+     * @see setupUi() Qt Designer generated UI initialization
+     */
     PReplaceConfirmationDialog(QWidget *parent = nullptr);
+
+    /**
+     * @brief Virtual destructor.
+     *
+     * @details Default destructor implementation. Qt's parent-child ownership
+     * system automatically handles cleanup of UI elements created by setupUi().
+     * No manual resource cleanup is required.
+     *
+     * @note Declared virtual to ensure proper cleanup in inheritance
+     *       hierarchies, following C++ best practices.
+     */
     virtual ~PReplaceConfirmationDialog() {}
 };