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
- * and sets a proper key.
+ * \brief SAX callback invoked when an XML start tag is encountered.
+ *
+ * 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
- * the internal variables.
+ * \brief SAX callback invoked for text content between XML tags.
  *
- * \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
- * \param len not used
+ * Currently not used - CDATA blocks are ignored.
+ *
+ * \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
- * @param fln
+ * \brief Constructor that loads TrimSP range distribution data.
+ *
+ * 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
- * @return true on success.
+ * Parses the two-column format from TrimSP output:
+ * - 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)
- * @return zMax if energy is found, -1 otherwise.
+ * Searches for a data set matching the specified energy (within 0.9 keV
+ * 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)
 {
@@ -567,7 +627,7 @@ Double_t PRgeHandler::GetZmax(const Double_t energy)
       break;
     }
   }
-  
+
   if (idx != -1)
       return GetZmax(idx);
 
@@ -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.
- * @return zMax if idx is in range, -1 otherwise.
+ * Returns the last depth value from the depth vector, which represents
+ * 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)
- * @param z (nm)
- * @return n(E,z) if energy and z are in proper range, -1.0 otherwise.
+ * Searches for a data set matching the specified energy (within 0.9 keV
+ * tolerance) and returns the normalized distribution value at depth z.
+ *
+ * \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
- * @param z (nm)
- * @return n(idx,z) if idx and z are in proper range, -1.0 otherwise.
+ * Uses linear interpolation between adjacent data points to compute the
+ * distribution value at the requested depth. The normalization ensures
+ * 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).
- * @return energy index if energy was found, -1 otherwise.
+ * Searches through loaded data sets for a matching energy value using a
+ * 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)
 {