improve doxygen documentation of PRgeHandler.*

src/classes/PRgeHandler.cpp

@@ -45,7 +45,10 @@ ClassImpQ(PXmlRgeHandler)
 // OnStartDocument
 //--------------------------------------------------------------------------
 /**
- * <p>Called on start of the XML file reading. Initializes all necessary variables.
+ * \brief SAX callback invoked at the start of XML document parsing.
+ *
+ * Initializes the parsing state by resetting the key to empty. This ensures
+ * clean state for processing the XML content.
  */
 void PXmlRgeHandler::OnStartDocument()
 {
@@ -56,7 +59,14 @@ void PXmlRgeHandler::OnStartDocument()
 // OnEndDocument
 //--------------------------------------------------------------------------
 /**
- * <p>Called on end of XML file reading.
+ * \brief SAX callback invoked at the end of XML document parsing.
+ *
+ * Performs final validation to ensure all required fields were parsed:
+ * - TrimSP data path must be set
+ * - RGE filename prefix must be set
+ * - At least one implantation energy must be specified
+ *
+ * Sets fIsValid to false and calls OnError() if any validation fails.
  */
 void PXmlRgeHandler::OnEndDocument()
 {
@@ -85,11 +95,19 @@ void PXmlRgeHandler::OnEndDocument()
 // OnStartElement
 //--------------------------------------------------------------------------
 /**
- * <p>Called when a XML start element is found. Filters out the needed elements
+ * \brief SAX callback invoked when an XML start tag is encountered.
- * and sets a proper key.
+ *
+ * Processes recognized elements within the <trim_sp> section:
+ * - <data_path>: Directory containing RGE files
+ * - <rge_fln_pre>: RGE filename prefix
+ * - <energy>: Single implantation energy value
+ * - <energy_vect>: Energy range with start/stop/step attributes
+ *
+ * For <energy_vect>, parses the attributes and generates the energy list.
+ * Performs extensive validation on attribute values and ranges.
  *
  * \param str XML element name
- * \param attributes used only for energy_vect
+ * \param attributes Element attributes (only used for energy_vect)
  */
 void PXmlRgeHandler::OnStartElement(const Char_t *str, const TList *attributes)
 {
@@ -182,9 +200,12 @@ void PXmlRgeHandler::OnStartElement(const Char_t *str, const TList *attributes)
 // OnEndElement
 //--------------------------------------------------------------------------
 /**
- * <p>Called when a XML end element is found. Resets the handler key.
+ * \brief SAX callback invoked when an XML end tag is encountered.
  *
- * \param str not used
+ * Resets the parsing state when leaving the <trim_sp> section and
+ * clears the current element key for all end tags.
+ *
+ * \param str XML element name
  */
 void PXmlRgeHandler::OnEndElement(const Char_t *str)
 {
@@ -199,10 +220,17 @@ void PXmlRgeHandler::OnEndElement(const Char_t *str)
 // OnCharacters
 //--------------------------------------------------------------------------
 /**
- * <p>Content of a given XML element. Filters out the data and feeds them to
+ * \brief SAX callback invoked for text content between XML tags.
- * the internal variables.
  *
- * \param str XML element string
+ * Processes the content based on the current parsing state (fKey):
+ * - eDataPath: Stores the data directory path
+ * - eFlnPre: Stores the RGE filename prefix
+ * - eEnergy: Parses integer energy value and adds to energy list
+ *
+ * Performs validation and error handling for energy values, ensuring
+ * they are valid integers within range.
+ *
+ * \param str Text content from XML element
  */
 void PXmlRgeHandler::OnCharacters(const Char_t *str)
 {
@@ -249,9 +277,11 @@ void PXmlRgeHandler::OnCharacters(const Char_t *str)
 // OnComment
 //--------------------------------------------------------------------------
 /**
- * <p>Called when a XML comment is found. Not used.
+ * \brief SAX callback invoked for XML comments.
  *
- * \param str not used.
+ * Currently not used - comments are ignored.
+ *
+ * \param str Comment text
  */
 void PXmlRgeHandler::OnComment(const Char_t *str)
 {
@@ -262,9 +292,11 @@ void PXmlRgeHandler::OnComment(const Char_t *str)
 // OnWarning
 //--------------------------------------------------------------------------
 /**
- * <p>Called when the XML parser emits a warning.
+ * \brief SAX callback invoked when the parser emits a warning.
  *
- * \param str warning string
+ * Prints warning message to stderr.
+ *
+ * \param str Warning message from parser
  */
 void PXmlRgeHandler::OnWarning(const Char_t *str)
 {
@@ -276,9 +308,12 @@ void PXmlRgeHandler::OnWarning(const Char_t *str)
 // OnError
 //--------------------------------------------------------------------------
 /**
- * <p>Called when the XML parser emits an error.
+ * \brief SAX callback invoked when the parser encounters an error.
  *
- * \param str error string
+ * Prints error message to stderr. Called both by the parser and
+ * by this handler's own validation code.
+ *
+ * \param str Error message
  */
 void PXmlRgeHandler::OnError(const Char_t *str)
 {
@@ -290,9 +325,11 @@ void PXmlRgeHandler::OnError(const Char_t *str)
 // OnFatalError
 //--------------------------------------------------------------------------
 /**
- * <p>Called when the XML parser emits a fatal error.
+ * \brief SAX callback invoked when the parser encounters a fatal error.
  *
- * \param str fatal error string
+ * Prints fatal error message to stderr. Fatal errors typically stop parsing.
+ *
+ * \param str Fatal error message
  */
 void PXmlRgeHandler::OnFatalError(const Char_t *str)
 {
@@ -304,10 +341,12 @@ void PXmlRgeHandler::OnFatalError(const Char_t *str)
 // OnCdataBlock
 //--------------------------------------------------------------------------
 /**
- * <p>Not used.
+ * \brief SAX callback invoked for CDATA blocks.
  *
- * \param str not used
+ * Currently not used - CDATA blocks are ignored.
- * \param len not used
+ *
+ * \param str CDATA content
+ * \param len Length of CDATA content
  */
 void PXmlRgeHandler::OnCdataBlock(const Char_t *str, Int_t len)
 {
@@ -322,8 +361,18 @@ ClassImp(PRgeHandler)
 // Ctor
 //--------------------------------------------------------------------------
 /**
- * @brief PRgeHandler::PRgeHandler
+ * \brief Constructor that loads TrimSP range distribution data.
- * @param fln
+ *
+ * Performs the following steps:
+ * 1. Validates that XML configuration filename is provided
+ * 2. Parses XML file using PXmlRgeHandler to get file paths and energies
+ * 3. Reads all specified .rge files from TrimSP
+ * 4. Calculates total particle counts for each energy
+ * 5. Computes normalized distributions nn(z) where ∫nn(z)dz = 1
+ *
+ * Sets fValid to false if any errors occur during loading.
+ *
+ * \param fln Path to XML configuration file (empty triggers error)
  */
 PRgeHandler::PRgeHandler(const std::string fln)
 {
@@ -440,10 +489,18 @@ PRgeHandler::PRgeHandler(const std::string fln)
 // ReadRgeFile
 //--------------------------------------------------------------------------
 /**
- * <p>Read the content of a rge-file.
+ * \brief Reads a single TrimSP .rge file and populates a PRgeData structure.
  *
- * @param fln file name of the rge-file
+ * Parses the two-column format from TrimSP output:
- * @return true on success.
+ * - Column 1: Depth in Ångström (converted to nm by dividing by 10)
+ * - Column 2: Number of particles (amplitude)
+ *
+ * Skips empty lines and non-numeric lines. Performs extensive validation
+ * on numeric values with detailed error messages.
+ *
+ * \param fln Path to the .rge file
+ * \param data PRgeData structure to populate with depth and amplitude vectors
+ * \return True on success, false if file cannot be opened or contains invalid data
  */
 bool PRgeHandler::ReadRgeFile(const std::string fln, PRgeData &data)
 {
@@ -553,10 +610,13 @@ bool PRgeHandler::ReadRgeFile(const std::string fln, PRgeData &data)
 // GetZmax via energy
 //--------------------------------------------------------------------------
 /**
- * <p>Get maximal depth for a given energy.
+ * \brief Returns maximum penetration depth for a given implantation energy.
  *
- * @param energy energy in (eV)
+ * Searches for a data set matching the specified energy (within 0.9 keV
- * @return zMax if energy is found, -1 otherwise.
+ * tolerance) and returns its maximum depth value.
+ *
+ * \param energy Implantation energy in eV
+ * \return Maximum depth in nm, or -1 if energy not found
  */
 Double_t PRgeHandler::GetZmax(const Double_t energy)
 {
@@ -578,10 +638,13 @@ Double_t PRgeHandler::GetZmax(const Double_t energy)
 // GetZmax via index
 //--------------------------------------------------------------------------
 /**
- * <p>Get maximal depth for a given index.
+ * \brief Returns maximum penetration depth for a given data set index.
  *
- * @param idx index for which zMax is requested.
+ * Returns the last depth value from the depth vector, which represents
- * @return zMax if idx is in range, -1 otherwise.
+ * the maximum penetration depth for this energy.
+ *
+ * \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
+ * \return Maximum depth in nm, or -1 if idx out of range
  */
 Double_t PRgeHandler::GetZmax(const Int_t idx)
 {
@@ -595,11 +658,14 @@ Double_t PRgeHandler::GetZmax(const Int_t idx)
 // Get_n via energy
 //--------------------------------------------------------------------------
 /**
- * <p>Get the normalized n(E,z) value.
+ * \brief Returns normalized particle distribution at given energy and depth.
  *
- * @param energy (eV)
+ * Searches for a data set matching the specified energy (within 0.9 keV
- * @param z (nm)
+ * tolerance) and returns the normalized distribution value at depth z.
- * @return n(E,z) if energy and z are in proper range, -1.0 otherwise.
+ *
+ * \param energy Implantation energy in eV
+ * \param z Depth in nm
+ * \return Normalized distribution nn(E,z), or 0.0 if energy not found or z out of range
  */
 Double_t PRgeHandler::Get_n(const Double_t energy, const Double_t z)
 {
@@ -620,11 +686,17 @@ Double_t PRgeHandler::Get_n(const Double_t energy, const Double_t z)
 // Get_n via index
 //--------------------------------------------------------------------------
 /**
- * <p>Get the normalized n(idx,z) value.
+ * \brief Returns normalized particle distribution at given index and depth.
  *
- * @param idx index of the rge-dataset
+ * Uses linear interpolation between adjacent data points to compute the
- * @param z (nm)
+ * distribution value at the requested depth. The normalization ensures
- * @return n(idx,z) if idx and z are in proper range, -1.0 otherwise.
+ * that ∫nn(z)dz = 1 over the entire depth range.
+ *
+ * Special handling for z near zero: extrapolates linearly from first data point.
+ *
+ * \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
+ * \param z Depth in nm
+ * \return Normalized distribution nn(idx,z), or 0.0 if idx or z out of range
  */
 Double_t PRgeHandler::Get_n(const Int_t idx, const Double_t z)
 {
@@ -658,10 +730,13 @@ Double_t PRgeHandler::Get_n(const Int_t idx, const Double_t z)
 // GetEnergyIndex
 //--------------------------------------------------------------------------
 /**
- * <p>Get the energy index by providing an energy in (eV).
+ * \brief Finds the data set index corresponding to a given implantation energy.
  *
- * @param energy in (eV).
+ * Searches through loaded data sets for a matching energy value using a
- * @return energy index if energy was found, -1 otherwise.
+ * tolerance of 0.9 keV (i.e., |E_data - E_query| < 0.9 keV).
+ *
+ * \param energy Implantation energy in eV
+ * \return Data set index (0 to GetNoOfRgeDataSets()-1), or -1 if not found
  */
 Int_t PRgeHandler::GetEnergyIndex(const Double_t energy)
 {

src/include/PRgeHandler.h

@@ -41,86 +41,271 @@
 
 //-----------------------------------------------------------------------------
 /**
- * <p>Keep a single rge table from TrimSP for a given energy.
+ * \brief Data structure for a single TrimSP range distribution at a given energy.
+ *
+ * PRgeData stores the muon/particle implantation depth profile calculated by
+ * TrimSP (Transport of Ions in Matter - Stopping and Range) for a specific
+ * implantation energy. It contains the depth distribution n(z) and normalized
+ * distribution nn(z) where ∫nn(z)dz = 1.
+ *
+ * \see PRgeHandler for the class that reads and manages RGE data
+ * \see PRgeDataList for collections of RGE data sets
  */
 struct PRgeData {
-  Double_t energy;
+  Double_t energy;          ///< Implantation energy in eV
-  PDoubleVector depth;
+  PDoubleVector depth;      ///< Depth values in nanometers (nm)
-  PDoubleVector amplitude;
+  PDoubleVector amplitude;  ///< Number of particles at each depth (raw counts from TrimSP)
-  PDoubleVector nn; // normalized int n(z) dz = 1 amplitudes
+  PDoubleVector nn;         ///< Normalized particle density where ∫nn(z)dz = 1
-  Double_t noOfParticles;
+  Double_t noOfParticles;   ///< Total number of particles (sum of amplitudes)
 };
 
 //-----------------------------------------------------------------------------
 /**
- * <p>Keep all rge tables from TrimSP.
+ * \brief Container for multiple TrimSP range distributions at different energies.
+ *
+ * PRgeDataList is a vector of PRgeData structures, typically containing
+ * implantation profiles for a range of energies (e.g., 1-30 keV).
  */
 typedef std::vector<PRgeData> PRgeDataList;
 
 //-----------------------------------------------------------------------------
 /**
- * <p>Reads the xml-startup file in order to extract all necessary information
+ * \brief XML SAX parser handler for TrimSP configuration files.
- * about the RGE files (TrimSP) needed.
+ *
+ * PXmlRgeHandler parses XML configuration files to extract TrimSP (Transport
+ * of Ions in Matter) data file locations and parameters. The XML file specifies:
+ * - Data path: Directory containing .rge files
+ * - Filename prefix: Base name for RGE files (e.g., "LCCO_E")
+ * - Energy list: Implantation energies (individual values or start/stop/step)
+ *
+ * This handler implements ROOT's TSAXParser callbacks for event-driven XML parsing.
+ *
+ * \par XML Format Example:
+ * \code{.xml}
+ * <trim_sp>
+ *   <data_path>/path/to/rge/files</data_path>
+ *   <rge_fln_pre>Material_E</rge_fln_pre>
+ *   <energy>1000</energy>
+ *   <energy>5000</energy>
+ *   <energy_vect start="10000" stop="30000" step="1000"/>
+ * </trim_sp>
+ * \endcode
+ *
+ * \see PRgeHandler for the main RGE data manager
+ * \see TSAXParser for ROOT's SAX parser implementation
  */
 class PXmlRgeHandler : public TObject, public TQObject
 {
   public:
+    /// Default constructor
     PXmlRgeHandler() {}
+    /// Destructor
     virtual ~PXmlRgeHandler() {}
 
+    /// Called at start of XML document parsing (SLOT)
     virtual void OnStartDocument(); // SLOT
+    /// Called at end of XML document parsing, performs validation (SLOT)
     virtual void OnEndDocument(); // SLOT
-    virtual void OnStartElement(const char*, const TList*); // SLOT
+    /**
-    virtual void OnEndElement(const char*); // SLOT
+     * \brief Called when XML start tag is encountered (SLOT)
-    virtual void OnCharacters(const char*); // SLOT
+     * \param str Element name
-    virtual void OnComment(const char*); // SLOT
+     * \param attributes Element attributes (used for energy_vect)
-    virtual void OnWarning(const char*); // SLOT
+     */
-    virtual void OnError(const char*); // SLOT
+    virtual void OnStartElement(const char* str, const TList* attributes); // SLOT
-    virtual void OnFatalError(const char*); // SLOT
+    /**
-    virtual void OnCdataBlock(const char*, Int_t); // SLOT
+     * \brief Called when XML end tag is encountered (SLOT)
+     * \param str Element name
+     */
+    virtual void OnEndElement(const char* str); // SLOT
+    /**
+     * \brief Called for element content between tags (SLOT)
+     * \param str Character data
+     */
+    virtual void OnCharacters(const char* str); // SLOT
+    /**
+     * \brief Called for XML comments (SLOT)
+     * \param str Comment text
+     */
+    virtual void OnComment(const char* str); // SLOT
+    /**
+     * \brief Called when parser emits a warning (SLOT)
+     * \param str Warning message
+     */
+    virtual void OnWarning(const char* str); // SLOT
+    /**
+     * \brief Called when parser encounters an error (SLOT)
+     * \param str Error message
+     */
+    virtual void OnError(const char* str); // SLOT
+    /**
+     * \brief Called when parser encounters a fatal error (SLOT)
+     * \param str Fatal error message
+     */
+    virtual void OnFatalError(const char* str); // SLOT
+    /**
+     * \brief Called for CDATA blocks (SLOT)
+     * \param str CDATA content
+     * \param len Length of CDATA
+     */
+    virtual void OnCdataBlock(const char* str, Int_t len); // SLOT
 
+    /**
+     * \brief Returns validity status of parsed configuration.
+     * \return True if XML was parsed successfully and all required fields are present
+     */
     virtual bool IsValid() { return fIsValid; }
+
+    /**
+     * \brief Returns the TrimSP data directory path.
+     * \return Directory path containing .rge files
+     */
     virtual std::string GetTrimSpDataPath() { return fTrimSpDataPath; }
+
+    /**
+     * \brief Returns the RGE filename prefix.
+     * \return Filename prefix (e.g., "LCCO_E" for files like LCCO_E1000.rge)
+     */
     virtual std::string GetTrimSpFlnPre() { return fTrimSpFlnPre; }
+
+    /**
+     * \brief Returns the list of implantation energies.
+     * \return Vector of energies in eV
+     */
     virtual const PIntVector GetTrimSpDataVectorList() const { return fTrimSpDataEnergyList; }
 
   private:
+    /// Enum for tracking which XML element is currently being parsed
     enum EKeyWords {eEmpty, eDataPath, eFlnPre, eEnergy};
-    EKeyWords      fKey;
+    EKeyWords      fKey;              ///< Current parsing context/state
 
-    bool isTrimSp{false};
+    bool isTrimSp{false};             ///< True when inside <trim_sp> element
-    bool fIsValid{true};
+    bool fIsValid{true};              ///< Validity flag (false if parsing errors occur)
 
-    std::string fTrimSpDataPath{""}; //< where to find the rge-files
+    std::string fTrimSpDataPath{""};  ///< Directory path to RGE files
-    std::string fTrimSpFlnPre{""};   //< keeps the preface of the rge file name, e.g. LCCO_E
+    std::string fTrimSpFlnPre{""};    ///< RGE filename prefix (e.g., "LCCO_E" for LCCO_E1000.rge)
-    PIntVector  fTrimSpDataEnergyList; //< TrimSP implantation energy list (in eV)
+    PIntVector  fTrimSpDataEnergyList; ///< List of implantation energies in eV
 
   ClassDef(PXmlRgeHandler, 1)
 };
 
 //-----------------------------------------------------------------------------
 /**
- * @brief The PRegHandler class
+ * \brief Manager for TrimSP range distribution data.
+ *
+ * PRgeHandler reads and manages muon/particle implantation depth profiles
+ * calculated by TrimSP (Transport of Ions in Matter - Stopping and Range).
+ * It provides access to:
+ * - Particle implantation depth distributions n(E,z)
+ * - Normalized distributions nn(E,z) where ∫nn(z)dz = 1
+ * - Maximum penetration depths for different energies
+ *
+ * The class loads RGE files specified in an XML configuration file, which
+ * can contain data for multiple implantation energies. RGE files contain
+ * depth (in Ångström) vs. particle count data from TrimSP simulations.
+ *
+ * \par Typical Usage:
+ * \code
+ * PRgeHandler rge("config.xml");
+ * if (rge.IsValid()) {
+ *   Double_t zmax = rge.GetZmax(5000.0);  // Max depth at 5 keV
+ *   Double_t n = rge.Get_n(5000.0, 10.0); // Distribution at 5 keV, 10 nm depth
+ * }
+ * \endcode
+ *
+ * \see PRgeData for the data structure holding individual distributions
+ * \see PXmlRgeHandler for XML configuration parsing
  */
 class PRgeHandler : public TObject
 {
   public:
+    /**
+     * \brief Constructor that loads TrimSP data from XML configuration.
+     * \param fln Path to XML configuration file (empty string for manual setup)
+     *
+     * Parses the XML file to get RGE file locations and energies, then loads
+     * all specified RGE files. Sets fValid to false if any errors occur.
+     */
     PRgeHandler(std::string fln="");
+
+    /// Destructor
     virtual ~PRgeHandler() {}
 
+    /**
+     * \brief Returns validity status.
+     * \return True if all RGE files loaded successfully, false if errors occurred
+     */
     virtual bool IsValid() { return fValid; }
+
+    /**
+     * \brief Returns number of loaded RGE data sets.
+     * \return Number of energy data sets (one per energy value)
+     */
     virtual UInt_t GetNoOfRgeDataSets() { return (UInt_t)fData.size(); }
+
+    /**
+     * \brief Returns all RGE data sets.
+     * \return Vector of all loaded PRgeData structures
+     */
     virtual PRgeDataList GetRgeData() { return fData; }
+
+    /**
+     * \brief Returns maximum penetration depth for a given energy.
+     * \param energy Implantation energy in eV
+     * \return Maximum depth in nm, or -1 if energy not found
+     */
     virtual Double_t GetZmax(const Double_t energy);
+
+    /**
+     * \brief Returns maximum penetration depth for a data set index.
+     * \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
+     * \return Maximum depth in nm, or -1 if idx out of range
+     */
     virtual Double_t GetZmax(const Int_t idx);
+
+    /**
+     * \brief Returns normalized particle distribution at given energy and depth.
+     * \param energy Implantation energy in eV
+     * \param z Depth in nm
+     * \return Normalized distribution nn(E,z), or 0.0 if out of range
+     *
+     * Uses linear interpolation between data points. The normalization ensures
+     * that ∫nn(z)dz = 1 over the entire depth range.
+     */
     virtual Double_t Get_n(const Double_t energy, const Double_t z);
+
+    /**
+     * \brief Returns normalized particle distribution at given index and depth.
+     * \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
+     * \param z Depth in nm
+     * \return Normalized distribution nn(idx,z), or 0.0 if out of range
+     *
+     * Uses linear interpolation between data points. The normalization ensures
+     * that ∫nn(z)dz = 1 over the entire depth range.
+     */
     virtual Double_t Get_n(const Int_t idx, const Double_t z);
+
+    /**
+     * \brief Finds the data set index for a given energy.
+     * \param energy Implantation energy in eV
+     * \return Data set index, or -1 if energy not found
+     *
+     * Uses tolerance of 0.9 keV for matching energies.
+     */
     virtual Int_t GetEnergyIndex(const Double_t energy);
 
   private:
-    bool fValid{false};
+    bool fValid{false};               ///< Validity flag (true if all RGE files loaded successfully)
-    PRgeDataList fData;
+    PRgeDataList fData;               ///< Collection of RGE data sets (one per energy)
 
+    /**
+     * \brief Reads a single RGE file and populates a PRgeData structure.
+     * \param fln Path to the .rge file
+     * \param data PRgeData structure to populate
+     * \return True on success, false on error
+     *
+     * Parses the two-column format (depth amplitude) from TrimSP output.
+     * Converts depth from Ångström to nanometers.
+     */
     virtual bool ReadRgeFile(const std::string fln, PRgeData &data);
 
   ClassDef(PRgeHandler, 1)