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

src/musredit_qt6/mupp/PmuppAdmin.cpp

@@ -27,6 +27,30 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PmuppAdmin.cpp
+ *
+ * @brief Implementation of mupp configuration and administration classes.
+ *
+ * This file implements the configuration management system for mupp, including:
+ * - XML parsing of the mupp_startup.xml configuration file
+ * - Recent file history management
+ * - Plot appearance settings (colors and markers)
+ * - Theme preferences for UI elements
+ * - Automatic creation of default configuration files
+ *
+ * The implementation provides:
+ * - PmuppColor: RGB color storage and manipulation
+ * - PmuppAdminXMLParser: XML configuration file parsing
+ * - PmuppAdmin: Main configuration manager with file search hierarchy
+ *
+ * Configuration file handling:
+ * - Searches multiple standard locations for configuration
+ * - Creates default configuration if none found
+ * - Automatically saves recent file history on exit
+ * - Validates configuration values (marker codes, RGB ranges)
+ */
+
 #include <cstdlib>
 #include <iostream>
 
@@ -48,7 +72,10 @@
 // implementation of PmuppColor class
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppColor::PmuppColor. Ctor
+ * @brief Default constructor for PmuppColor.
+ *
+ * Initializes a color with an "UnDef" name and invalid RGB values (-1).
+ * Invalid values indicate the color has not been properly initialized.
  */
 PmuppColor::PmuppColor()
 {
@@ -60,10 +87,15 @@ PmuppColor::PmuppColor()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppColor::setRGB. set RGB value
+ * @brief Sets the RGB color values with validation.
- * @param r red (0..255)
+ *
- * @param g green (0..255)
+ * Sets the red, green, and blue components of the color. Each component
- * @param b blue (0..255)
+ * is validated to be in the range [0, 255]. Values outside this range
+ * are ignored and the corresponding component remains unchanged.
+ *
+ * @param r red component (0-255)
+ * @param g green component (0-255)
+ * @param b blue component (0-255)
  */
 void PmuppColor::setRGB(const int r, const int g, const int b)
 {
@@ -79,9 +111,14 @@ void PmuppColor::setRGB(const int r, const int g, const int b)
 // implementation of PmuppAdminXMLParser class
 //--------------------------------------------------------------------------
 /**
- * <p>XML Parser class for the mupp administration file.
+ * @brief Constructor for XML parser.
  *
- * \param admin pointer to an admin class instance.
+ * Initializes the XML parser and attempts to open and parse the
+ * specified configuration file. The parsed data is stored in the
+ * provided PmuppAdmin object.
+ *
+ * @param fln path to the mupp_startup.xml configuration file
+ * @param admin pointer to the PmuppAdmin instance to populate with parsed data
  */
 PmuppAdminXMLParser::PmuppAdminXMLParser(const QString& fln, PmuppAdmin *admin) : fAdmin(admin)
 {
@@ -98,11 +135,18 @@ PmuppAdminXMLParser::PmuppAdminXMLParser(const QString& fln, PmuppAdmin *admin)
 
 //--------------------------------------------------------------------------
 /**
- * <p>parse the mupp startup xml-file.
+ * @brief Parses the mupp startup XML file.
  *
- * \param device QFile object of the mupp startup xml-file
+ * This method uses Qt's QXmlStreamReader to parse the configuration file.
+ * It processes each XML element sequentially, calling appropriate handler
+ * methods (startElement, characters, endElement) based on the element type.
  *
- * @return true on success, false otherwise
+ * The parser is event-driven and maintains state through the fKeyWord
+ * enumeration to determine how to process element content.
+ *
+ * @param device QIODevice (typically QFile) containing the XML data
+ *
+ * @return true if parsing succeeds without errors, false otherwise
  */
 bool PmuppAdminXMLParser::parse(QIODevice *device)
 {
@@ -137,7 +181,12 @@ bool PmuppAdminXMLParser::parse(QIODevice *device)
 
 //--------------------------------------------------------------------------
 /**
- * <p>Routine called at the beginning of the XML parsing process.
+ * @brief Handler called at the start of XML document parsing.
+ *
+ * This is invoked when the XML parser encounters the document start.
+ * Currently performs no actions but provides a hook for future initialization.
+ *
+ * @return always returns true
  */
 bool PmuppAdminXMLParser::startDocument()
 {
@@ -147,8 +196,22 @@ bool PmuppAdminXMLParser::startDocument()
 
 //--------------------------------------------------------------------------
 /**
- * <p>Routine called when a new XML tag is found. Here it is used
+ * @brief Handler called when a new XML element is encountered.
- * to set a tag for filtering afterwards the content.
+ *
+ * This method is invoked when the parser encounters an opening XML tag.
+ * It identifies the element type and sets the fKeyWord state accordingly,
+ * which determines how the element's content will be processed in the
+ * characters() method.
+ *
+ * Recognized elements:
+ * - path_file_name: Recent file entry
+ * - ignore_theme_auto_detection: Theme detection override
+ * - dark_theme_icon_menu: Menu icon theme
+ * - dark_theme_icon_toolbar: Toolbar icon theme
+ * - marker: Plot marker definition
+ * - color: RGB color definition
+ *
+ * @return always returns true
  */
 bool PmuppAdminXMLParser::startElement()
 {
@@ -173,9 +236,13 @@ bool PmuppAdminXMLParser::startElement()
 
 //--------------------------------------------------------------------------
 /**
- * <p>Routine called when the end XML tag is found. It is used to
+ * @brief Handler called when an XML closing tag is encountered.
- * put the filtering tag to 'empty'. It also resets the fFunc flag in case
+ *
- * the entry was a theory function.
+ * This method is invoked when the parser encounters a closing XML tag.
+ * It resets the fKeyWord state to eEmpty, ending the current element's
+ * context for content processing.
+ *
+ * @return always returns true
  */
 bool PmuppAdminXMLParser::endElement()
 {
@@ -186,8 +253,21 @@ bool PmuppAdminXMLParser::endElement()
 
 //--------------------------------------------------------------------------
 /**
- * <p>This routine delivers the content of an XML tag. It fills the
+ * @brief Handler called to process XML element content.
- * content into the load data structure.
+ *
+ * This method processes the text content between XML opening and closing
+ * tags. The content interpretation depends on the current fKeyWord state
+ * (set by startElement).
+ *
+ * Content processing by element type:
+ * - eRecentFile: Adds file path to recent files list
+ * - eIgnoreThemeAutoDetection: Sets theme auto-detection flag (yes/no/true/false)
+ * - eDarkThemeIconsMenu: Sets menu icon theme preference
+ * - eDarkThemeIconsToolbar: Sets toolbar icon theme preference
+ * - eMarker: Parses marker definition (code[,size])
+ * - eColor: Parses RGB color definition (r,g,b[,name])
+ *
+ * @return true if content is valid, false on parsing errors
  */
 bool PmuppAdminXMLParser::characters()
 {
@@ -273,8 +353,13 @@ bool PmuppAdminXMLParser::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.
+ *
+ * This is invoked when the parser reaches the end of the XML document.
+ * Currently performs no post-processing but provides a hook for future
+ * finalization tasks such as path expansion or validation.
+ *
+ * @return always returns true
  */
 bool PmuppAdminXMLParser::endDocument()
 {
@@ -285,8 +370,20 @@ bool PmuppAdminXMLParser::endDocument()
 // implementation of PmuppAdmin class
 //--------------------------------------------------------------------------
 /**
- * <p>Initializes that PmuppAdmin object, and calls the XML parser which feeds
+ * @brief Constructor for PmuppAdmin.
- * the object variables.
+ *
+ * Initializes the administration object and searches for a configuration
+ * file in multiple standard locations. The search proceeds in order:
+ * 1. Current directory (./mupp_startup.xml)
+ * 2. User home directory ($HOME/.musrfit/mupp/mupp_startup.xml)
+ * 3. MUSRFITPATH directory ($MUSRFITPATH/mupp_startup.xml)
+ * 4. ROOTSYS directory ($ROOTSYS/bin/mupp_startup.xml)
+ *
+ * If no configuration file is found, creates a default one in the user's
+ * home directory using the embedded resource template.
+ *
+ * The constructor loads all configuration settings including recent files,
+ * markers, colors, and theme preferences via the PmuppAdminXMLParser.
  */
 PmuppAdmin::PmuppAdmin() : QObject()
 {
@@ -336,7 +433,11 @@ PmuppAdmin::PmuppAdmin() : QObject()
 
 //--------------------------------------------------------------------------
 /**
- * <p>Destructor
+ * @brief Destructor for PmuppAdmin.
+ *
+ * Saves the current recent file list to the configuration file before
+ * destruction. This ensures that the file history is preserved across
+ * application sessions.
  */
 PmuppAdmin::~PmuppAdmin()
 {
@@ -345,9 +446,14 @@ PmuppAdmin::~PmuppAdmin()
 
 //--------------------------------------------------------------------------
 /**
- * <p>Add recent path-file name to the internal ring-buffer.
+ * @brief Adds a file to the recent files list.
  *
- * \param str recent path-file name to be added
+ * Adds a file path to the front of the recent files ring buffer. If the
+ * file is already in the list, it is not added again (no duplicates).
+ * The list is limited to MAX_RECENT_FILES entries; older entries are
+ * removed when the limit is exceeded.
+ *
+ * @param str the full path and filename to add to recent files
  */
 void PmuppAdmin::addRecentFile(const QString str)
 {
@@ -364,12 +470,14 @@ void PmuppAdmin::addRecentFile(const QString str)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppAdmin::getRecentFile. Get a file from the recent files with
+ * @brief Retrieves a recent file path by index.
- * index idx.
- * @param idx
  *
- * @return return the recent file with index idx if present, otherwise return
+ * Returns the file path at the specified position in the recent files list.
- * an empty string.
+ * Index 0 refers to the most recently accessed file.
+ *
+ * @param idx zero-based index into the recent files list (0 is most recent)
+ *
+ * @return the file path if index is valid, or an empty string otherwise
  */
 QString PmuppAdmin::getRecentFile(int idx)
 {
@@ -383,10 +491,14 @@ QString PmuppAdmin::getRecentFile(int idx)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppAdmin::getMarker. Get the marker with index idx.
+ * @brief Retrieves a marker definition by index.
- * @param idx marker index
  *
- * @return requested marker
+ * Returns the marker at the specified index in the marker list.
+ * Markers are used to define the visual appearance of data points in plots.
+ *
+ * @param idx zero-based index into the marker list
+ *
+ * @return the marker definition if index is valid, or a default marker otherwise
  */
 PmuppMarker PmuppAdmin::getMarker(int idx) {
   PmuppMarker marker;
@@ -399,11 +511,15 @@ PmuppMarker PmuppAdmin::getMarker(int idx) {
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppAdmin::getColor. Get rgb color codes of name
+ * @brief Retrieves a color by name.
- * @param name of the requeset color.
+ *
- * @param r red value (0..255)
+ * Searches for a color with the specified name and returns its RGB values.
- * @param g green value (0..255)
+ * If the color is not found, all RGB components are set to -1.
- * @param b blue value (0..255
+ *
+ * @param name the name of the color to retrieve
+ * @param r output parameter: red component (0-255, or -1 if not found)
+ * @param g output parameter: green component (0-255, or -1 if not found)
+ * @param b output parameter: blue component (0-255, or -1 if not found)
  */
 void PmuppAdmin::getColor(QString name, int &r, int &g, int &b)
 {
@@ -426,11 +542,16 @@ void PmuppAdmin::getColor(QString name, int &r, int &g, int &b)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppAdmin::getColor. Get color codes of color at index idx
+ * @brief Retrieves a color by index.
- * @param idx requested color index
+ *
- * @param r red value (0..255)
+ * Returns the RGB values of the color at the specified index in the
- * @param g green value (0..255)
+ * color list. If the index is out of range, all RGB components are
- * @param b blue value (0..255)
+ * set to -1.
+ *
+ * @param idx zero-based index into the color list
+ * @param r output parameter: red component (0-255, or -1 if invalid index)
+ * @param g output parameter: green component (0-255, or -1 if invalid index)
+ * @param b output parameter: blue component (0-255, or -1 if invalid index)
  */
 void PmuppAdmin::getColor(int idx, int &r, int &g, int &b)
 {
@@ -445,9 +566,14 @@ void PmuppAdmin::getColor(int idx, int &r, int &g, int &b)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppAdmin::setMaker. Set a marker
+ * @brief Adds a marker definition to the configuration.
- * @param marker marker code
+ *
- * @param size marker size
+ * Creates a new marker with the specified code and size, validates it,
+ * and adds it to the marker list. Marker codes must be in the range 1-49
+ * (following ROOT conventions). Invalid markers are rejected with a warning.
+ *
+ * @param marker the marker code (1-49, ROOT style marker codes)
+ * @param size the marker size multiplier
  */
 void PmuppAdmin::setMarker(const int marker, const double size)
 {
@@ -466,11 +592,16 @@ void PmuppAdmin::setMarker(const int marker, const double size)
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppAdmin::setColor. Set a color
+ * @brief Adds a color definition to the configuration.
- * @param r red value (0..255)
+ *
- * @param g green value (0..255)
+ * Creates a new color with the specified RGB values and optional name,
- * @param b blue value (0..255)
+ * validates it, and adds it to the color list. RGB values must be in
- * @param name color name
+ * the range 0-255. Invalid colors are rejected with a warning.
+ *
+ * @param r red component (0-255)
+ * @param g green component (0-255)
+ * @param b blue component (0-255)
+ * @param name optional name for the color (empty by default)
  */
 void PmuppAdmin::setColor(const int r, const int g, const int b, QString name)
 {
@@ -490,9 +621,21 @@ void PmuppAdmin::setColor(const int r, const int g, const int b, QString name)
 
 //--------------------------------------------------------------------------
 /**
- * <p>Merges the recent file ring buffer into mupp_startup.xml and saves it.
+ * @brief Saves the recent files list to the configuration file.
- * If a local copy is present it will be saved there, otherwise the master file
+ *
- * will be used.
+ * Updates the mupp_startup.xml file with the current recent file list.
+ * The method first searches for a local configuration file in the current
+ * directory; if not found, it uses the user's home directory version
+ * ($HOME/.musrfit/mupp/mupp_startup.xml).
+ *
+ * The implementation:
+ * 1. Reads the entire configuration file into memory
+ * 2. Removes all existing \<path_file_name\> entries
+ * 3. Inserts current recent files list
+ * 4. Writes the updated configuration back to disk
+ *
+ * This preserves all other configuration settings while updating only
+ * the recent file history.
  */
 void PmuppAdmin::saveRecentFiles()
 {
@@ -561,8 +704,20 @@ void PmuppAdmin::saveRecentFiles()
 
 //--------------------------------------------------------------------------
 /**
- * @brief PmuppAdmin::createMuppStartupFile. Create a default mupp_startup.xml
+ * @brief Creates a default mupp_startup.xml configuration file.
- * file if not present.
+ *
+ * This method is called when no configuration file is found in any of
+ * the standard locations. It creates a new default configuration file
+ * in the user's home directory ($HOME/.musrfit/mupp/mupp_startup.xml).
+ *
+ * The implementation:
+ * 1. Creates the directory $HOME/.musrfit/mupp if it doesn't exist
+ * 2. Loads the default template from embedded resources (mupp_startup.xml.in)
+ * 3. Writes the template to the user's home directory
+ *
+ * The default configuration includes standard marker styles, color
+ * definitions, and empty recent file list, providing a working baseline
+ * for new users or clean installations.
  */
 void PmuppAdmin::createMuppStartupFile()
 {

src/musredit_qt6/mupp/PmuppAdmin.h

@@ -27,6 +27,32 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PmuppAdmin.h
+ *
+ * @brief Administration and configuration management for mupp application.
+ *
+ * This header file defines classes for managing mupp's configuration and
+ * user preferences. It provides functionality for:
+ * - Reading and parsing XML configuration files (mupp_startup.xml)
+ * - Managing recent file history
+ * - Storing plot appearance settings (colors, markers)
+ * - Handling theme preferences (light/dark mode icons)
+ *
+ * The configuration system supports multiple file locations with the
+ * following search priority:
+ * 1. Local directory (./mupp_startup.xml)
+ * 2. User home (~/.musrfit/mupp/mupp_startup.xml)
+ * 3. MUSRFITPATH environment variable location
+ * 4. ROOTSYS/bin location
+ *
+ * Key components:
+ * - PmuppColor: RGB color definitions for plot elements
+ * - PmuppMarker: Marker style and size specifications
+ * - PmuppAdminXMLParser: XML parser for configuration files
+ * - PmuppAdmin: Main administration class managing all settings
+ */
+
 #ifndef _PMUPPADMIN_H_
 #define _PMUPPADMIN_H_
 
@@ -42,134 +68,418 @@ class PmuppAdmin;
 
 //---------------------------------------------------------------------------
 /**
- * @brief The PmuppColor class. Contains to colors read from the xml-startup
+ * @brief Represents an RGB color for plotting.
- * which are used for the plotted data.
+ *
+ * The PmuppColor class encapsulates a named color with RGB components.
+ * Colors are read from the XML startup configuration file and used for
+ * plotting data points, lines, and other graphical elements in mupp.
+ *
+ * Each color has:
+ * - A name identifier (optional)
+ * - RGB values in the range 0-255
+ *
+ * These colors allow users to customize the appearance of plots and
+ * ensure consistency across different data collections.
  */
 class PmuppColor {
   public:
+    /**
+     * @brief Default constructor. Initializes color with undefined values.
+     */
     PmuppColor();
+
+    /**
+     * @brief Destructor.
+     */
     virtual ~PmuppColor() {}
 
+    /**
+     * @brief Gets the color name.
+     * @return the name identifier of the color
+     */
     QString getName() { return fName; }
+
+    /**
+     * @brief Gets the RGB values of the color.
+     * @param r output parameter: red component (0-255)
+     * @param g output parameter: green component (0-255)
+     * @param b output parameter: blue component (0-255)
+     */
     void getRGB(int &r, int &g, int &b) { r=fRed; g=fGreen; b=fBlue; }
 
+    /**
+     * @brief Sets the color name.
+     * @param name the name identifier to assign to this color
+     */
     void setName(const QString name) { fName = name; }
+
+    /**
+     * @brief Sets the RGB values with validation.
+     * @param r red component (0-255)
+     * @param g green component (0-255)
+     * @param b blue component (0-255)
+     */
     void setRGB(const int r, const int g, const int b);
 
   private:
-    QString fName;    
+    QString fName;    ///< optional name identifier for the color
-    int fRed;
+    int fRed;         ///< red component (0-255)
-    int fGreen;
+    int fGreen;       ///< green component (0-255)
-    int fBlue;
+    int fBlue;        ///< blue component (0-255)
 };
 
 //---------------------------------------------------------------------------
 /**
- * @brief The PmuppMarker class. List of the markers used in the plotter. Read
+ * @brief Represents a plot marker style and size.
- * from the xml-startup.
+ *
+ * The PmuppMarker class encapsulates marker properties used for plotting
+ * data points in mupp. Markers are read from the XML startup configuration
+ * file and define the visual appearance of data points in plots.
+ *
+ * Each marker has:
+ * - A marker code (1-49, following ROOT marker conventions)
+ * - A size multiplier (relative to default size)
+ *
+ * Different markers allow users to visually distinguish between multiple
+ * data series in a single plot.
  */
 class PmuppMarker {
   public:
+    /**
+     * @brief Default constructor. Initializes with marker code 20 and size 1.0.
+     */
     PmuppMarker() { fMarker = 20; fMarkerSize = 1.0; }
+
+    /**
+     * @brief Constructor with specified marker properties.
+     * @param marker the marker code (1-49)
+     * @param size the marker size multiplier
+     */
     PmuppMarker(int marker, double size) : fMarker(marker), fMarkerSize(size) {}
+
+    /**
+     * @brief Destructor.
+     */
     virtual ~PmuppMarker() {}
 
+    /**
+     * @brief Gets both marker code and size.
+     * @param marker output parameter: marker code
+     * @param size output parameter: marker size multiplier
+     */
     void getMarker(int &marker, double &size) { marker = fMarker; size = fMarkerSize; }
+
+    /**
+     * @brief Gets the marker code.
+     * @return the marker code (1-49)
+     */
     int getMarker() { return fMarker; }
+
+    /**
+     * @brief Gets the marker size multiplier.
+     * @return the marker size multiplier
+     */
     double getMarkerSize() { return fMarkerSize; }
 
+    /**
+     * @brief Sets the marker code.
+     * @param marker the marker code to set (1-49)
+     */
     void setMarker(int marker) { fMarker = marker; }
+
+    /**
+     * @brief Sets the marker size multiplier.
+     * @param size the size multiplier to set
+     */
     void setMarkerSize(double size) { fMarkerSize = size; }
 
   private:
-    int fMarker;
+    int fMarker;         ///< marker code (1-49, ROOT style)
-    double fMarkerSize;
+    double fMarkerSize;  ///< size multiplier (1.0 = default size)
 };
 
 //---------------------------------------------------------------------------
 /**
- * PAdminXMLParser is an XML parser class used to handle the mupp startup
+ * @brief XML parser for mupp configuration files.
- * XML-file called <tt>mupp_startup.xml</tt>. This startup file contains
+ *
- * necessary informations about executable pathes, online help informations,
+ * PmuppAdminXMLParser is responsible for reading and parsing the mupp
- * default font sizes, etc.
+ * startup XML file (mupp_startup.xml). This configuration file contains:
+ * - Recent file history
+ * - Theme preferences (light/dark mode icons)
+ * - Plot marker styles and sizes
+ * - Plot color definitions
+ *
+ * The parser uses Qt's QXmlStreamReader for efficient XML processing
+ * and populates a PmuppAdmin object with the configuration data.
+ *
+ * XML structure handled:
+ * - \<recent_files\>: List of recently opened files
+ * - \<ignore_theme_auto_detection\>: Theme detection override
+ * - \<dark_theme_icon_menu\>: Menu icon theme preference
+ * - \<dark_theme_icon_toolbar\>: Toolbar icon theme preference
+ * - \<marker\>: Plot marker definitions
+ * - \<color\>: RGB color definitions
  */
 class PmuppAdminXMLParser
 {
   public:
+    /**
+     * @brief Constructor that parses the XML configuration file.
+     * @param fln path to the mupp_startup.xml file
+     * @param admin pointer to PmuppAdmin object to populate with parsed data
+     */
     PmuppAdminXMLParser(const QString &fln, PmuppAdmin*);
+
+    /**
+     * @brief Destructor.
+     */
     virtual ~PmuppAdminXMLParser() {}
 
+    /**
+     * @brief Checks if the XML parsing was successful.
+     * @return true if parsing succeeded, false otherwise
+     */
     virtual bool isValid() { return fValid; }
 
   private:
-    enum EAdminKeyWords {eEmpty, eRecentFile,
+    /**
-                         eIgnoreThemeAutoDetection, eDarkThemeIconsMenu, eDarkThemeIconsToolbar,
+     * @brief Enumeration of recognized XML element types.
-                         eMarker, eColor};
+     *
+     * These keywords determine how to process the content of each XML element.
+     */
+    enum EAdminKeyWords {eEmpty,                     ///< no specific element being processed
+                         eRecentFile,                ///< recent file path element
+                         eIgnoreThemeAutoDetection,  ///< theme auto-detection override
+                         eDarkThemeIconsMenu,        ///< menu icon theme setting
+                         eDarkThemeIconsToolbar,     ///< toolbar icon theme setting
+                         eMarker,                    ///< marker definition element
+                         eColor};                    ///< color definition element
 
+    /**
+     * @brief Main parsing method that processes the XML document.
+     * @param device QIODevice containing the XML data to parse
+     * @return true if parsing succeeds, false on error
+     */
     bool parse(QIODevice *device);
+
+    /**
+     * @brief Handler for XML document start.
+     * @return true if successful
+     */
     bool startDocument();
+
+    /**
+     * @brief Handler for XML element opening tags.
+     * @return true if successful
+     */
     bool startElement();
+
+    /**
+     * @brief Handler for XML element closing tags.
+     * @return true if successful
+     */
     bool endElement();
+
+    /**
+     * @brief Handler for XML element text content.
+     * @return true if content is valid, false on error
+     */
     bool characters();
+
+    /**
+     * @brief Handler for XML document end.
+     * @return true if successful
+     */
     bool endDocument();
 
-    QXmlStreamReader fXml;     ///< xml stream reader object
+    QXmlStreamReader fXml;     ///< Qt XML stream reader object for parsing
-    bool             fValid;   ///< flag showing if XML read has been successful
+    bool             fValid;   ///< flag indicating successful XML parsing
-    EAdminKeyWords   fKeyWord; ///< key word tag to know how to handle the content
+    EAdminKeyWords   fKeyWord; ///< current element type being processed
-    PmuppAdmin       *fAdmin;  ///< a pointer to the main administration class object
+    PmuppAdmin       *fAdmin;  ///< pointer to the admin object being populated
 };
 
 //---------------------------------------------------------------------------
 /**
- * The PMuppAdmin class is handling the informations contained in the XML startup file,
+ * @brief Main administration class for mupp configuration management.
- * <tt>mupp_startup.xml</tt>. This startup file contains
+ *
- * necessary informations like marker style, marker color, etc. The XML parsing is done
+ * The PmuppAdmin class manages all configuration settings and user preferences
- * with the help of the PmuppAdminXMLParser class.
+ * for the mupp application. It loads settings from the XML startup file
+ * (mupp_startup.xml) and provides access to:
+ * - Recent file history (up to MAX_RECENT_FILES entries)
+ * - Plot appearance settings (markers and colors)
+ * - Theme preferences for UI icons
+ *
+ * Configuration file search order:
+ * 1. ./mupp_startup.xml (local directory)
+ * 2. $HOME/.musrfit/mupp/mupp_startup.xml (user home)
+ * 3. $MUSRFITPATH/mupp_startup.xml (installation directory)
+ * 4. $ROOTSYS/bin/mupp_startup.xml (ROOT installation)
+ *
+ * If no configuration file is found, a default one is created in the
+ * user's home directory (~/.musrfit/mupp/).
+ *
+ * The class automatically saves the recent file list when destroyed,
+ * updating the configuration file with the current session's file history.
  */
 class PmuppAdmin : public QObject
 {
   public:
+    /**
+     * @brief Constructor. Loads configuration from mupp_startup.xml.
+     */
     PmuppAdmin();
+
+    /**
+     * @brief Destructor. Saves recent files list before destruction.
+     */
     virtual ~PmuppAdmin();
 
+    /**
+     * @brief Adds a file to the recent files list.
+     * @param str the file path to add
+     */
     void    addRecentFile(const QString str);
+
+    /**
+     * @brief Gets the number of recent files.
+     * @return the count of recent files stored (maximum MAX_RECENT_FILES)
+     */
     int     getNumRecentFiles() { return fRecentFile.size(); }
+
+    /**
+     * @brief Gets a recent file path by index.
+     * @param idx zero-based index (0 is most recent)
+     * @return the file path, or empty string if index is out of range
+     */
     QString getRecentFile(int idx);
 
-
+    /**
-
+     * @brief Gets the number of configured markers.
+     * @return the count of marker definitions
+     */
     int getNoOfMarkers() { return fMarker.size(); }
+
+    /**
+     * @brief Gets all markers.
+     * @return vector of all marker definitions
+     */
     QVector<PmuppMarker> getMarkers() { return fMarker; }
+
+    /**
+     * @brief Gets a marker definition by index.
+     * @param idx zero-based index into the marker list
+     * @return the marker definition, or default marker if index is out of range
+     */
     PmuppMarker getMarker(int idx);
 
+    /**
+     * @brief Gets the number of configured colors.
+     * @return the count of color definitions
+     */
     int getNoOfColors() { return fColor.size(); }
+
+    /**
+     * @brief Gets all colors.
+     * @return vector of all color definitions
+     */
     QVector<PmuppColor> getColors() { return fColor; }
+
+    /**
+     * @brief Gets a color by name.
+     * @param name the color name to search for
+     * @param r output parameter: red component (0-255, or -1 if not found)
+     * @param g output parameter: green component (0-255, or -1 if not found)
+     * @param b output parameter: blue component (0-255, or -1 if not found)
+     */
     void getColor(QString name, int &r, int &g, int &b);
+
+    /**
+     * @brief Gets a color by index.
+     * @param idx zero-based index into the color list
+     * @param r output parameter: red component (0-255, or -1 if invalid)
+     * @param g output parameter: green component (0-255, or -1 if invalid)
+     * @param b output parameter: blue component (0-255, or -1 if invalid)
+     */
     void getColor(int idx, int &r, int &g, int &b);
 
+    /**
+     * @brief Checks if theme auto-detection should be ignored.
+     * @return true if auto-detection is disabled, false otherwise
+     */
     bool getIgnoreThemeAutoDetection() { return fIgnoreThemeAutoDetection; }
+
+    /**
+     * @brief Checks if dark theme icons should be used for menus.
+     * @return true if dark theme icons are enabled for menus
+     */
     bool getDarkThemeIconsMenuFlag() { return fDarkThemeIconsMenu; }
+
+    /**
+     * @brief Checks if dark theme icons should be used for toolbars.
+     * @return true if dark theme icons are enabled for toolbars
+     */
     bool getDarkThemeIconsToolbarFlag() { return fDarkThemeIconsToolbar; }
 
+    /**
+     * @brief Sets the theme auto-detection preference.
+     * @param theme true to ignore auto-detection, false to enable it
+     */
     void setIgnoreThemeAutoDetection(const bool theme) { fIgnoreThemeAutoDetection = theme; }
+
+    /**
+     * @brief Sets the menu icon theme preference.
+     * @param theme true for dark theme icons, false for light theme icons
+     */
     void setThemeIconsMenu(const bool theme) { fDarkThemeIconsMenu = theme; }
+
+    /**
+     * @brief Sets the toolbar icon theme preference.
+     * @param theme true for dark theme icons, false for light theme icons
+     */
     void setThemeIconsToolbar(const bool theme) { fDarkThemeIconsToolbar = theme; }
+
+    /**
+     * @brief Adds a marker definition to the configuration.
+     * @param marker the marker code (1-49, ROOT style)
+     * @param size the marker size multiplier
+     */
     void setMarker(const int marker, const double size);
+
+    /**
+     * @brief Adds a color definition to the configuration.
+     * @param r red component (0-255)
+     * @param g green component (0-255)
+     * @param b blue component (0-255)
+     * @param name optional name for the color
+     */
     void setColor(const int r, const int g, const int b, QString name="");
 
   private:
     friend class PmuppAdminXMLParser;
 
-    QVector<QString> fRecentFile; ///< keep vector of recent path-file names
+    QVector<QString> fRecentFile; ///< ring buffer of recent file paths (max MAX_RECENT_FILES)
 
-    bool fIgnoreThemeAutoDetection{false};
+    bool fIgnoreThemeAutoDetection{false}; ///< flag to override automatic theme detection
-    bool fDarkThemeIconsMenu{false};
+    bool fDarkThemeIconsMenu{false};       ///< flag for dark theme menu icons
-    bool fDarkThemeIconsToolbar{false};
+    bool fDarkThemeIconsToolbar{false};    ///< flag for dark theme toolbar icons
-    QVector<PmuppMarker> fMarker;
+    QVector<PmuppMarker> fMarker;          ///< vector of configured plot markers
-    QVector<PmuppColor> fColor;
+    QVector<PmuppColor> fColor;            ///< vector of configured plot colors
 
-    void saveRecentFiles(); ///< save recent file list
+    /**
-    void createMuppStartupFile(); ///< create default mupp_startup.xml
+     * @brief Saves the recent files list to the configuration file.
+     *
+     * Updates mupp_startup.xml with current recent file history while
+     * preserving other configuration settings.
+     */
+    void saveRecentFiles();
+
+    /**
+     * @brief Creates a default mupp_startup.xml configuration file.
+     *
+     * Called when no configuration file is found. Creates the file in
+     * $HOME/.musrfit/mupp/ using the embedded resource template.
+     */
+    void createMuppStartupFile();
 };
 
 #endif // _PMUPPADMIN_H_