improve the doxygen docu of the BMWtools.

src/external/BMWtools/BMWStartupHandler.h

@@ -30,6 +30,16 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file BMWStartupHandler.h
+ * @brief Header file for the XML startup file handler for BMW tools.
+ *
+ * This file contains the BMWStartupHandler class which parses the BMW_startup.xml
+ * configuration file and provides default settings for the BMWtools plugin libraries.
+ *
+ * @author Bastian M. Wojek (based on PStartupHandler.h by Andreas Suter)
+ */
+
 #ifndef _BMWSTARTUPHANDLER_H_
 #define _BMWSTARTUPHANDLER_H_
 
@@ -40,32 +50,36 @@
 #include <map>
 
 /**
- * <p>Handles the XML musrfit startup file (BMW_startup.xml) where default settings for some plugin libraries are stored:
- * - TRIM.SP data file path and energies
- * - time and field resolutions for Fourier transforms
- * - paths to FFTW3 wisdom files (double and float)
- * - number of steps for one-dimensional theory functions (where needed)
- * - number of steps for two-dimensional grids when calculating spatial field distributions in vortex lattices
- * - time resolutions and lengths of Laplace transforms used in the calculation of LF-relaxation functions
- * - flag for debugging the information contained in the startup file
+ * @class BMWStartupHandler
+ * @brief Handles the XML musrfit startup file (BMW_startup.xml) where default settings for plugin libraries are stored.
+ *
+ * This class is a SAX2-based XML parser handler that reads and processes the BMW_startup.xml configuration file.
+ * The configuration file contains default settings for:
+ * - TRIM.SP data file path and energies (for low-energy muon implantation profiles)
+ * - Time and field resolutions for Fourier transforms
+ * - Paths to FFTW3 wisdom files (double and float precision)
+ * - Number of steps for one-dimensional theory functions (where needed)
+ * - Number of steps for two-dimensional grids when calculating spatial field distributions in vortex lattices
+ * - Time resolutions and lengths of Laplace transforms used in the calculation of LF-relaxation functions
+ * - Debug flag for verbose output of the information contained in the startup file
  */
 class BMWStartupHandler : public TQObject {
   public:
     BMWStartupHandler();
     virtual ~BMWStartupHandler();
 
-    virtual void OnStartDocument(); // SLOT
-    virtual void OnEndDocument(); // SLOT
-    virtual void OnStartElement(const char*, const TList*); // SLOT
-    virtual void OnEndElement(const char*); // SLOT
-    virtual void OnCharacters(const char*); // SLOT
-    virtual void OnComment(const char*); // SLOT
-    virtual void OnWarning(const char*); // SLOT
-    virtual void OnError(const char*); // SLOT
-    virtual void OnFatalError(const char*); // SLOT
-    virtual void OnCdataBlock(const char*, int); // SLOT
+    virtual void OnStartDocument(); ///< Called when XML parsing begins
+    virtual void OnEndDocument(); ///< Called when XML parsing ends
+    virtual void OnStartElement(const char*, const TList*); ///< Called when an XML element starts
+    virtual void OnEndElement(const char*); ///< Called when an XML element ends
+    virtual void OnCharacters(const char*); ///< Called when XML character data is encountered
+    virtual void OnComment(const char*); ///< Called when an XML comment is encountered
+    virtual void OnWarning(const char*); ///< Called when the XML parser emits a warning
+    virtual void OnError(const char*); ///< Called when the XML parser emits an error
+    virtual void OnFatalError(const char*); ///< Called when the XML parser emits a fatal error
+    virtual void OnCdataBlock(const char*, int); ///< Called when an XML CDATA block is encountered
 
-    virtual void CheckLists();
+    virtual void CheckLists(); ///< Validates and sets default values for configuration parameters
 
     virtual const std::string GetDataPath() const { return fDataPath; } ///< returns the path to TRIM.SP files
     virtual std::map<double, std::string> GetEnergies() const { return fEnergies; } ///< returns energies and file labels of available TRIM.SP files
@@ -80,28 +94,31 @@ class BMWStartupHandler : public TQObject {
     virtual const bool GetDebug() const { return fDebug; } ///< true = debug the xml-entries
 
   private:
+    /**
+     * @brief Enumeration of XML element keywords used for parsing.
+     */
     enum EKeyWords {eEmpty, eComment, eDebug, eLEM, eVortex, eLF, eDataPath, eEnergyLabel, \
                     eEnergy, eEnergyList, eDeltat, eDeltaB, eWisdomFile, eWisdomFileFloat, \
                     eNSteps, eGridSteps, eDeltatLF, eNStepsLF};
 
-    EKeyWords       fKey; ///< xml filter key
+    EKeyWords       fKey; ///< Current XML element being parsed
 
-    bool            fDebug;           ///< debug flag
-    bool            fLEM;             ///< low-energy muSR flag
-    bool            fVortex;          ///< vortex-lattice flag
-    bool            fLF;              ///< longitudinal-field flag
-    std::string     fDataPath;        ///< path to TRIM.SP files
-    std::vector<std::string> fEnergyLabelList; ///< file labels of the TRIM.SP files
-    std::vector<double> fEnergyList;  ///< muon implantation energies of the TRIM.SP files
-    std::map<double, std::string> fEnergies;   ///< muon implantation energies and file labels of the TRIM.SP files
-    double          fDeltat;          ///< time resolution of P(t) when using Fourier transforms
-    double          fDeltaB;          ///< field resolution of p(B) when using Fourier transforms
-    std::string     fWisdomFile;      ///< FFTW3 double-wisdom file
-    std::string     fWisdomFileFloat; ///< FFTW3 float-wisdom file
-    unsigned int    fNSteps;          ///< number of steps in one-dimensional theory functions
-    unsigned int    fGridSteps;       ///< number of steps in each direction when calculating two-dimensional spatial field distributions
-    double          fDeltatLF;        ///< time resolution of P(t) when using Laplace transforms for the calculation of LF-relaxation functions
-    unsigned int    fNStepsLF;        ///< length of the Laplace transforms for the calculation of LF-relaxation functions
+    bool            fDebug;           ///< Debug flag for verbose output
+    bool            fLEM;             ///< Low-energy muSR mode flag
+    bool            fVortex;          ///< Vortex lattice calculations flag
+    bool            fLF;              ///< Longitudinal field mode flag
+    std::string     fDataPath;        ///< Path to TRIM.SP data files directory
+    std::vector<std::string> fEnergyLabelList; ///< File name labels of the TRIM.SP files
+    std::vector<double> fEnergyList;  ///< Muon implantation energies in keV of the TRIM.SP files
+    std::map<double, std::string> fEnergies;   ///< Map of muon implantation energies (keV) to file labels
+    double          fDeltat;          ///< Time resolution in microseconds for P(t) when using Fourier transforms
+    double          fDeltaB;          ///< Field resolution in Gauss for p(B) when using Fourier transforms
+    std::string     fWisdomFile;      ///< Path to FFTW3 double-precision wisdom file
+    std::string     fWisdomFileFloat; ///< Path to FFTW3 single-precision wisdom file
+    unsigned int    fNSteps;          ///< Number of steps in one-dimensional theory functions
+    unsigned int    fGridSteps;       ///< Number of grid points in each direction for 2D spatial field distributions
+    double          fDeltatLF;        ///< Time resolution in microseconds for P(t) in LF Laplace transforms
+    unsigned int    fNStepsLF;        ///< Length of the Laplace transforms for LF relaxation functions
 
   ClassDef(BMWStartupHandler, 1)
 };