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

src/musredit_qt6/musredit/PChangeDefaultPathsDialog.cpp

@@ -27,6 +27,20 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PChangeDefaultPathsDialog.cpp
+ * @brief Implementation of classes for managing default data file search paths.
+ * @details This file implements the PDefaultPathsXMLParser, PDefaultPaths, and
+ * PChangeDefaultPathsDialog classes that together provide functionality for
+ * reading, displaying, editing, and saving the default search paths for muon
+ * data files.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ * @copyright Copyright (C) 2010-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #include <QString>
 #include <QStringView>
 #include <QMessageBox>
@@ -39,12 +53,19 @@
 
 #include "PChangeDefaultPathsDialog.h"
 
+//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+// Implementation of PDefaultPathsXMLParser
 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
- * <p>XML Parser class for the musrfit administration file.
+ * @brief Constructs an XML parser for reading default data paths.
  *
- * \param fln file name of the musredit startup xml-file
+ * @details Opens and parses the specified XML configuration file to extract
- * @param defaultPaths
+ * \<data_path\> elements. The parsed paths are stored in the provided
+ * PDefaultPaths object. After construction, call isValid() to check if
+ * parsing succeeded.
+ *
+ * @param fln Full path to the musrfit_startup.xml configuration file.
+ * @param defaultPaths Pointer to the PDefaultPaths object to populate with parsed paths.
  */
 PDefaultPathsXMLParser::PDefaultPathsXMLParser(const QString& fln, PDefaultPaths *defaultPaths) :
   fDefaultPaths(defaultPaths)
@@ -62,11 +83,17 @@ PDefaultPathsXMLParser::PDefaultPathsXMLParser(const QString& fln, PDefaultPaths
 
 //--------------------------------------------------------------------------
 /**
- * <p>parse the musrfit startup xml-file.
+ * @brief Parse the XML configuration file for data paths.
  *
- * \param device QFile object of the musrfit startup xml-file
+ * @details Reads the XML file using Qt's QXmlStreamReader, processing elements
+ * sequentially. Recognized \<data_path\> elements have their content extracted
+ * and added to the associated PDefaultPaths object.
  *
- * @return true on success, false otherwise
+ * @param device QIODevice (typically a QFile) opened for reading.
+ *
+ * @return true if parsing completed without XML errors, false otherwise.
+ *         On error, displays a message box with error details including
+ *         line and column numbers.
  */
 bool PDefaultPathsXMLParser::parse(QIODevice *device)
 {
@@ -101,7 +128,12 @@ bool PDefaultPathsXMLParser::parse(QIODevice *device)
 
 //--------------------------------------------------------------------------
 /**
- * <p>Routine called at the beginning of the XML parsing process.
+ * @brief Handler called at the start of XML document parsing.
+ *
+ * @details This method is invoked when the parser encounters the beginning
+ * of the XML document. Currently performs no initialization.
+ *
+ * @return Always returns true.
  */
 bool PDefaultPathsXMLParser::startDocument()
 {
@@ -111,8 +143,13 @@ bool PDefaultPathsXMLParser::startDocument()
 
 //--------------------------------------------------------------------------
 /**
- * <p>Routine called when a new XML tag is found. Here it is used
+ * @brief Handler called when an XML start element is encountered.
- * to set a tag for filtering afterwards the content.
+ *
+ * @details Sets the internal keyword flag based on the element name.
+ * Currently only recognizes \<data_path\> elements; all other elements
+ * are ignored.
+ *
+ * @return Always returns true.
  */
 bool PDefaultPathsXMLParser::startElement()
 {
@@ -127,8 +164,12 @@ bool PDefaultPathsXMLParser::startElement()
 
 //--------------------------------------------------------------------------
 /**
- * <p>Routine called when the end XML tag is found. It is used to
+ * @brief Handler called when an XML end element is encountered.
- * put the filtering tag to 'empty'.
+ *
+ * @details Resets the keyword flag to eEmpty after finishing processing
+ * of an element.
+ *
+ * @return Always returns true.
  */
 bool PDefaultPathsXMLParser::endElement()
 {
@@ -139,8 +180,13 @@ bool PDefaultPathsXMLParser::endElement()
 
 //--------------------------------------------------------------------------
 /**
- * <p>This routine delivers the content of an XML tag. It fills the
+ * @brief Handler for XML element character content.
- * content into the load data structure.
+ *
+ * @details Processes the text content of the current XML element. If the
+ * current element is a \<data_path\>, the content (directory path) is
+ * appended to the PDefaultPaths object.
+ *
+ * @return Always returns true.
  */
 bool PDefaultPathsXMLParser::characters()
 {
@@ -161,17 +207,37 @@ bool PDefaultPathsXMLParser::characters()
 
 //--------------------------------------------------------------------------
 /**
- * <p>Called at the end of the XML parse process. It checks if default paths
+ * @brief Handler called at the end of XML document parsing.
- * contain system variables, and if so expand them for the further use.
+ *
+ * @details This method is invoked when the parser reaches the end of the
+ * XML document. Currently performs no post-processing.
+ *
+ * @return Always returns true.
  */
 bool PDefaultPathsXMLParser::endDocument()
 {
   return true;
 }
 
+//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+// Implementation of PDefaultPaths
 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
- * @brief PDefaultPaths::PDefaultPaths
+ * @brief Constructs a PDefaultPaths object and loads paths from configuration.
+ *
+ * @details Searches for the musrfit_startup.xml configuration file in the
+ * standard search locations, then parses it to extract default data paths.
+ *
+ * @par Search Order:
+ * -# Current working directory (./musrfit_startup.xml)
+ * -# User's home directory ($HOME/.musrfit/musrfit_startup.xml)
+ * -# MUSRFITPATH environment variable ($MUSRFITPATH/musrfit_startup.xml)
+ * -# ROOT installation ($ROOTSYS/bin/musrfit_startup.xml)
+ *
+ * After construction, call isValid() to check if configuration was loaded
+ * successfully.
+ *
+ * @note Displays an error dialog if parsing fails.
  */
 PDefaultPaths::PDefaultPaths() : QObject()
 {
@@ -211,11 +277,23 @@ PDefaultPaths::PDefaultPaths() : QObject()
   }
 }
 
+//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+// Implementation of PChangeDefaultPathsDialog
 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 /**
- * <p>Constructor.
+ * @brief Constructs the default paths dialog.
  *
- * \param fAdmin keeps all the needed flags
+ * @details Initializes the dialog by:
+ * -# Creating a PDefaultPaths object to load current paths
+ * -# Setting up the UI from the .ui file
+ * -# Populating the list widget with existing paths
+ * -# Connecting button signals to handler slots
+ *
+ * The dialog is created as modal, blocking interaction with other windows
+ * until closed.
+ *
+ * @note If path loading fails (PDefaultPaths invalid), the constructor
+ * returns early without fully initializing the dialog.
  */
 PChangeDefaultPathsDialog::PChangeDefaultPathsDialog()
 {
@@ -243,7 +321,15 @@ PChangeDefaultPathsDialog::PChangeDefaultPathsDialog()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * @brief PChangeDefaultPathsDialog::addItem
+ * @brief Slot to add a new directory path to the list.
+ *
+ * @details Opens a directory selection dialog allowing the user to browse
+ * for and select a directory. If the user selects a directory (doesn't cancel),
+ * the path is inserted into the list widget immediately after the currently
+ * selected item.
+ *
+ * @note Uses QFileDialog configured to show only directories and not resolve
+ * symbolic links.
  */
 void PChangeDefaultPathsDialog::addItem()
 {
@@ -265,7 +351,10 @@ void PChangeDefaultPathsDialog::addItem()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * @brief PChangeDefaultPathsDialog::deleteItem
+ * @brief Slot to remove the currently selected path from the list.
+ *
+ * @details Removes the currently selected item from the list widget and
+ * frees its memory. If no item is selected, the method has no effect.
  */
 void PChangeDefaultPathsDialog::deleteItem()
 {
@@ -276,7 +365,20 @@ void PChangeDefaultPathsDialog::deleteItem()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * @brief PChangeDefaultPathsDialog::saveDefaultPathList
+ * @brief Slot to save the modified path list to the configuration file.
+ *
+ * @details Persists the current list of data paths to the musrfit_startup.xml
+ * configuration file. The method:
+ * -# Reads the existing configuration file content
+ * -# Removes all existing \<data_path\> elements
+ * -# Inserts the current list widget entries as new \<data_path\> elements
+ * -# Writes the modified content back to the file
+ *
+ * If no \<data_path\> elements existed in the original file, the new paths
+ * are inserted just before the closing \</musrfit\> tag.
+ *
+ * @note This slot is connected to the dialog's accept signal, so it is called
+ * automatically when the user clicks OK.
  */
 void PChangeDefaultPathsDialog::saveDefaultPathList()
 {

src/musredit_qt6/musredit/PChangeDefaultPathsDialog.h

@@ -27,6 +27,27 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PChangeDefaultPathsDialog.h
+ * @brief Dialog for managing default data file search paths in musredit.
+ * @details This header defines classes for managing the default search paths
+ * used by musrfit to locate data files. The paths are stored in the
+ * \c musrfit_startup.xml configuration file and can be edited through
+ * a graphical dialog.
+ *
+ * The file contains three main classes:
+ * - PDefaultPathsXMLParser: Parses \<data_path\> elements from XML
+ * - PDefaultPaths: Stores and manages the list of default paths
+ * - PChangeDefaultPathsDialog: Qt dialog for user interaction
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ * @copyright Copyright (C) 2010-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PAdmin For main configuration management
+ */
+
 #ifndef _PCHANGEDEFAULTPATHSDIALOG_H_
 #define _PCHANGEDEFAULTPATHSDIALOG_H_
 
@@ -42,16 +63,48 @@
 class PDefaultPaths;
 
 //---------------------------------------------------------------------------
+/**
+ * @class PDefaultPathsXMLParser
+ * @brief XML parser for extracting default data paths from configuration.
+ *
+ * @details This class parses the \c musrfit_startup.xml configuration file
+ * to extract the \<data_path\> elements that define default search directories
+ * for muon data files. The parser uses Qt's QXmlStreamReader for efficient
+ * streaming XML parsing.
+ *
+ * @par XML Format:
+ * The parser expects elements in the form:
+ * @code{.xml}
+ * <data_path>/path/to/data/directory</data_path>
+ * @endcode
+ *
+ * @see PDefaultPaths The class that stores the parsed paths
+ */
 class PDefaultPathsXMLParser
 {
   public:
     PDefaultPathsXMLParser(const QString &fln, PDefaultPaths *defaultPaths);
+
+    /**
+     * @brief Virtual destructor.
+     */
     virtual ~PDefaultPathsXMLParser() {}
 
+    /**
+     * @brief Check if the XML file was parsed successfully.
+     * @return true if parsing succeeded, false otherwise.
+     */
     virtual bool isValid() { return fValid; }
 
   private:
-    enum EAdminKeyWords {eEmpty, eDataPath};
+    /**
+     * @enum EAdminKeyWords
+     * @brief Keywords for identifying XML elements during parsing.
+     */
+    enum EAdminKeyWords {
+      eEmpty,    ///< No element currently being processed.
+      eDataPath  ///< Processing a \<data_path\> element.
+    };
 
     bool parse(QIODevice *device);
     bool startDocument();
@@ -60,33 +113,99 @@ class PDefaultPathsXMLParser
     bool characters();
     bool endDocument();
 
-    QXmlStreamReader fXml;        ///< xml stream reader object
+    QXmlStreamReader fXml;        ///< Qt XML stream reader for parsing.
-    bool             fValid;      ///< flag showing if XML read has been successful
+    bool             fValid;      ///< Flag indicating successful parsing.
-    EAdminKeyWords   fKeyWord;    ///< key word tag to know how to handle the content
+    EAdminKeyWords   fKeyWord;    ///< Current element type being processed.
-    PDefaultPaths *fDefaultPaths; ///< keeps the default search paths for the data files
+    PDefaultPaths *fDefaultPaths; ///< Pointer to the object storing parsed paths.
 };
 
 //---------------------------------------------------------------------------
+/**
+ * @class PDefaultPaths
+ * @brief Container class for managing default data file search paths.
+ *
+ * @details This class loads and stores the list of default directory paths
+ * where musrfit searches for muon data files. The paths are read from
+ * the \c musrfit_startup.xml configuration file during construction.
+ *
+ * The configuration file is searched in the following order:
+ * -# Current working directory
+ * -# \c $HOME/.musrfit/
+ * -# \c $MUSRFITPATH/
+ * -# \c $ROOTSYS/bin/
+ *
+ * @see PDefaultPathsXMLParser For the XML parsing implementation
+ * @see PChangeDefaultPathsDialog For the user interface to edit paths
+ */
 class PDefaultPaths : public QObject
 {
   public:
     PDefaultPaths();
+
+    /**
+     * @brief Virtual destructor.
+     */
     virtual ~PDefaultPaths() {}
 
+    /**
+     * @brief Check if the configuration was loaded successfully.
+     * @return true if valid, false if loading failed.
+     */
     virtual bool isValid() { return fValid; }
+
+    /**
+     * @brief Add a new path to the default paths list.
+     * @param str Directory path to add.
+     */
     virtual void appendDefaultPath(QString str) { fDefaultPath << str; }
+
+    /**
+     * @brief Get the list of default search paths.
+     * @return Pointer to the QStringList containing all paths.
+     */
     virtual QStringList *getDefaultPathList() { return &fDefaultPath; }
+
+    /**
+     * @brief Get the path to the configuration file being used.
+     * @return Full path to the musrfit_startup.xml file.
+     */
     virtual QString getPrefPathName() { return fPrefPathName; }
 
   private:
-    friend class PDefaultPathsXMLParser;
+    friend class PDefaultPathsXMLParser;  ///< Allow parser to access private members.
 
-    bool fValid;
+    bool fValid;              ///< Flag indicating if configuration loaded successfully.
-    QString fPrefPathName;
+    QString fPrefPathName;    ///< Full path to the active configuration file.
-    QStringList fDefaultPath;
+    QStringList fDefaultPath; ///< List of default data file search directories.
 };
 
 //---------------------------------------------------------------------------
+/**
+ * @class PChangeDefaultPathsDialog
+ * @brief Dialog for editing default data file search paths.
+ *
+ * @details This dialog provides a graphical interface for users to view, add,
+ * and remove the default directory paths where musrfit searches for muon
+ * spin rotation data files.
+ *
+ * @par Features:
+ * - Displays current search paths in a list widget
+ * - Add new paths via directory browser dialog
+ * - Delete selected paths from the list
+ * - Save changes back to the configuration file
+ *
+ * The dialog is modal and changes are persisted to musrfit_startup.xml
+ * when the user accepts the dialog (clicks OK).
+ *
+ * @par UI Elements:
+ * The dialog UI is defined in PChangeDefaultPathsDialog.ui and includes:
+ * - A list widget (fSearchPath_listWidget) showing current paths
+ * - Add button (fAdd_pushButton) to add new directories
+ * - Delete button (fDelete_pushButton) to remove selected path
+ * - Standard OK/Cancel button box
+ *
+ * @see PDefaultPaths For path storage and loading
+ */
 class PChangeDefaultPathsDialog : public QDialog, private Ui::PChangeDefaultPathsDialog
 {
   Q_OBJECT
@@ -95,12 +214,23 @@ class PChangeDefaultPathsDialog : public QDialog, private Ui::PChangeDefaultPath
     PChangeDefaultPathsDialog();
 
   private slots:
+    /**
+     * @brief Remove the currently selected path from the list.
+     */
     void deleteItem();
+
+    /**
+     * @brief Add a new directory path via file browser dialog.
+     */
     void addItem();
+
+    /**
+     * @brief Save the modified path list to the configuration file.
+     */
     void saveDefaultPathList();
 
   private:
-    std::unique_ptr<PDefaultPaths> fDefaultPath;
+    std::unique_ptr<PDefaultPaths> fDefaultPath;  ///< Manages the default paths data.
 };
 
 #endif // _PCHANGEDEFAULTPATHSDIALOG_H_