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

src/musredit_qt6/musredit/PDumpOutputHandler.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PDumpOutputHandler.cpp
+ * @brief Implementation of the PDumpOutputHandler class.
+ * @details This file implements the PDumpOutputHandler dialog which executes
+ * the dump_header command and displays its output. The implementation handles
+ * process lifecycle management, output capture, and proper cleanup.
+ *
+ * @author Andreas Suter
+ * @date 2012-2025
+ * @copyright Copyright (C) 2012-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #include <QTimer>
 
 #include <QtDebug>
@@ -35,9 +48,25 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Sets up the dump output handler GUI and starts the actual dump_header command
+ * @brief Constructs the dump output handler dialog and starts the command.
  *
- * \param cmd command string vector. From this the actual dump_header command will be generated and executed.
+ * @details Initializes the dialog UI and starts the dump_header process. The
+ * constructor performs the following steps:
+ * -# Creates the dialog layout with a text output area and Quit button
+ * -# Configures the process environment with appropriate library paths
+ * -# Extracts the program and arguments from the command vector
+ * -# Starts the process and connects output signals to display slots
+ *
+ * @par Environment Configuration:
+ * - On macOS: Sets DYLD_LIBRARY_PATH to include $ROOTSYS/lib
+ * - On Linux: Sets LD_LIBRARY_PATH to include $ROOTSYS/lib
+ *
+ * @param cmd Command vector where cmd[0] is the executable path and
+ *            subsequent elements are command-line arguments.
+ *
+ * @note If the command vector is empty, the constructor returns immediately
+ * without creating the UI. If the process fails to start, an error dialog
+ * is displayed.
  */
 PDumpOutputHandler::PDumpOutputHandler(QVector<QString> &cmd)
 {
@@ -92,7 +121,17 @@ PDumpOutputHandler::PDumpOutputHandler(QVector<QString> &cmd)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Destructor. Checks if the a dump_header is still running and if yes try to kill it.
+ * @brief Destructor - ensures the dump_header process is terminated.
+ *
+ * @details Performs cleanup by ensuring the child process is properly terminated.
+ * The termination sequence is:
+ * -# Attempt graceful termination with QProcess::terminate()
+ * -# Wait for process to finish
+ * -# If still running, use QProcess::kill()
+ * -# As a last resort, use system kill -9 command
+ *
+ * This multi-stage approach ensures the process doesn't become orphaned,
+ * even if it doesn't respond to normal termination signals.
  */
 PDumpOutputHandler::~PDumpOutputHandler()
 {
@@ -114,7 +153,12 @@ PDumpOutputHandler::~PDumpOutputHandler()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Captures the standard output and adds it to the output text edit.
+ * @brief Slot to capture and display standard output from the process.
+ *
+ * @details Reads all available data from the process's standard output stream
+ * and appends it to the text display widget. This slot is connected to the
+ * QProcess::readyReadStandardOutput signal and may be called multiple times
+ * as output arrives in chunks.
  */
 void PDumpOutputHandler::readFromStdOut()
 {
@@ -125,7 +169,15 @@ void PDumpOutputHandler::readFromStdOut()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Captures the standard error and adds it to the output text edit.
+ * @brief Slot to capture and display standard error from the process.
+ *
+ * @details Reads all available data from the process's standard error stream
+ * and appends it to the text display widget. This slot is connected to the
+ * QProcess::readyReadStandardError signal and may be called multiple times
+ * as error output arrives in chunks.
+ *
+ * Error output is displayed alongside normal output in the same text widget,
+ * allowing users to see errors in context with regular output.
  */
 void PDumpOutputHandler::readFromStdErr()
 {
@@ -136,8 +188,15 @@ void PDumpOutputHandler::readFromStdErr()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>If the quit button is pressed while the dump_header is still running, try to terminate dump_header, if this
+ * @brief Slot called when the Quit button is pressed.
- * does not work, try to kill dump_header.
+ *
+ * @details Handles user request to close the dialog. If the dump_header process
+ * is still running, attempts to terminate it gracefully using QProcess::terminate().
+ * If graceful termination fails within the timeout period, forcefully kills
+ * the process using QProcess::kill().
+ *
+ * After ensuring the process is stopped, accepts the dialog (closes it with
+ * QDialog::Accepted result).
  */
 void PDumpOutputHandler::quitButtonPressed()
 {

src/musredit_qt6/musredit/PDumpOutputHandler.h

@@ -27,6 +27,22 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PDumpOutputHandler.h
+ * @brief Dialog for displaying dump_header command output.
+ * @details This header defines the PDumpOutputHandler class which provides
+ * a dialog window for executing the dump_header tool and displaying its
+ * output in real-time. The dump_header tool is used to display header
+ * information from muon data files.
+ *
+ * @author Andreas Suter
+ * @date 2012-2025
+ * @copyright Copyright (C) 2012-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PFitOutputHandler For similar output handling during fitting
+ */
+
 #ifndef _PDUMPOUTPUTHANDLER_H_
 #define _PDUMPOUTPUTHANDLER_H_
 
@@ -44,9 +60,34 @@
 
 //---------------------------------------------------------------------------------------
 /**
- * <p>This class is the capturing the output of musrfit and displays it in a dialog so
+ * @class PDumpOutputHandler
- * the user has the chance to follow the fitting process, warnings, error messages of
+ * @brief Dialog for executing and displaying dump_header command output.
- * musrfit.
+ *
+ * @details This class provides a modal dialog that executes the dump_header
+ * external command and displays its output in real-time. The dump_header tool
+ * is part of the musrfit suite and extracts header information from muon spin
+ * rotation/relaxation data files.
+ *
+ * @par Features:
+ * - Executes dump_header as a child process via QProcess
+ * - Captures both stdout and stderr output
+ * - Displays output in a read-only text widget
+ * - Provides a Quit button to terminate the process
+ * - Handles process cleanup on dialog close
+ *
+ * @par Usage:
+ * @code
+ * QVector<QString> cmd;
+ * cmd << "/path/to/dump_header" << "-f" << "datafile.root";
+ * PDumpOutputHandler dialog(cmd);
+ * dialog.exec();
+ * @endcode
+ *
+ * @par Platform Notes:
+ * - On macOS, sets DYLD_LIBRARY_PATH for ROOT library access
+ * - On Linux, sets LD_LIBRARY_PATH for ROOT library access
+ *
+ * @see PFitOutputHandler For similar handling of musrfit output
  */
 class PDumpOutputHandler : public QDialog
 {
@@ -57,17 +98,38 @@ class PDumpOutputHandler : public QDialog
     virtual ~PDumpOutputHandler();
 
   private slots:
+    /**
+     * @brief Slot to read and display standard output from the process.
+     */
     virtual void readFromStdOut();
+
+    /**
+     * @brief Slot to read and display standard error from the process.
+     */
     virtual void readFromStdErr();
+
+    /**
+     * @brief Slot called when the Quit button is pressed.
+     */
     virtual void quitButtonPressed();
 
-private:
+  private:
-    qint64 fProcPID; ///< keeps the process PID
+    /** @name Process Management
-    std::unique_ptr<QProcess> fProc; ///< pointer to the dump_header process
+     *  @brief Members for managing the external process.
+     *  @{
+     */
+    qint64 fProcPID;                   ///< Process ID of the running dump_header command.
+    std::unique_ptr<QProcess> fProc;   ///< QProcess object managing the dump_header execution.
+    /** @} */
 
-    std::unique_ptr<QVBoxLayout> fVbox; ///< pointer to the dialog layout manager
+    /** @name UI Components
-    std::unique_ptr<QTextEdit> fOutput; ///< the captured dump_header output is written (read only) into this text edit object.
+     *  @brief Dialog user interface elements.
-    std::unique_ptr<QPushButton> fQuitButton; ///< quit button
+     *  @{
+     */
+    std::unique_ptr<QVBoxLayout> fVbox;      ///< Vertical layout manager for dialog widgets.
+    std::unique_ptr<QTextEdit> fOutput;      ///< Read-only text widget displaying command output.
+    std::unique_ptr<QPushButton> fQuitButton; ///< Button to close dialog and terminate process.
+    /** @} */
 };
 
 #endif // _PDUMPOUTPUTHANDLER_H_