improve the doxygen docu of the BMWtools.

src/external/BMWtools/BMWStartupHandler.cpp

@@ -30,6 +30,16 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file BMWStartupHandler.cpp
+ * @brief Implementation of the XML startup file handler for BMW tools.
+ *
+ * This file implements the BMWStartupHandler class which parses the BMW_startup.xml
+ * configuration file using SAX2 XML parsing.
+ *
+ * @author Bastian M. Wojek (based on PStartupHandler.cpp by Andreas Suter)
+ */
+
 #include <cstdlib>
 #include <iostream>
 
@@ -39,22 +49,22 @@
 
 ClassImpQ(BMWStartupHandler)
 
-//--------------------------------------------------------------------------
-// Constructor
 //--------------------------------------------------------------------------
 /**
- * <p>Constructor. Check if the BMW_startup.xml file is found in the local directory
+ * @brief Constructor. Initializes all member variables to default values.
+ *
+ * The actual configuration will be loaded when the XML file is parsed.
  */
 BMWStartupHandler::BMWStartupHandler() :
  fDebug(false), fLEM(false), fVortex(false), fLF(false), fDataPath(""), fDeltat(0.), fDeltaB(0.), fWisdomFile(""), fWisdomFileFloat(""), fNSteps(0), fGridSteps(0), fDeltatLF(0.), fNStepsLF(0)
 {
 }
 
-//--------------------------------------------------------------------------
-// Destructor
 //--------------------------------------------------------------------------
 /**
- * <p>Destructor
+ * @brief Destructor. Cleans up allocated resources.
+ *
+ * Clears all internal vectors and maps.
  */
 BMWStartupHandler::~BMWStartupHandler()
 {
@@ -64,22 +74,23 @@ BMWStartupHandler::~BMWStartupHandler()
   fEnergies.clear();
 }
 
-//--------------------------------------------------------------------------
-// OnStartDocument
 //--------------------------------------------------------------------------
 /**
- * <p>Called on start of the XML file reading. Initializes all necessary variables.
+ * @brief Called on start of the XML file reading. Initializes all necessary variables.
+ *
+ * This method is automatically invoked by the SAX2 parser when parsing begins.
  */
 void BMWStartupHandler::OnStartDocument()
 {
   fKey = eEmpty;
 }
 
-//--------------------------------------------------------------------------
-// OnEndDocument
 //--------------------------------------------------------------------------
 /**
- * <p>Called on end of XML file reading.
+ * @brief Called on end of XML file reading.
+ *
+ * This method is automatically invoked by the SAX2 parser when parsing completes.
+ * It triggers validation and default value assignment.
  */
 void BMWStartupHandler::OnEndDocument()
 {
@@ -87,15 +98,13 @@ void BMWStartupHandler::OnEndDocument()
   CheckLists();
 }
 
-//--------------------------------------------------------------------------
-// OnStartElement
 //--------------------------------------------------------------------------
 /**
- * <p>Called when a XML start element is found. Filters out the needed elements
- * and sets a proper key.
+ * @brief Called when an XML start element is found. Filters out the needed elements
+ *        and sets a proper key.
  *
- * \param str XML element name
- * \param attributes not used
+ * @param str XML element name
+ * @param attributes XML attributes (not used)
  */
 void BMWStartupHandler::OnStartElement(const char *str, const TList *attributes)
 {
@@ -132,27 +141,23 @@ void BMWStartupHandler::OnStartElement(const char *str, const TList *attributes)
   }
 }
 
-//--------------------------------------------------------------------------
-// OnEndElement
 //--------------------------------------------------------------------------
 /**
- * <p>Called when a XML end element is found. Resets the handler key.
+ * @brief Called when an XML end element is found. Resets the handler key.
  *
- * \param str not used
+ * @param str XML element name (not used)
  */
 void BMWStartupHandler::OnEndElement(const char *str)
 {
   fKey = eEmpty;
 }
 
-//--------------------------------------------------------------------------
-// OnCharacters
 //--------------------------------------------------------------------------
 /**
- * <p>Content of a given XML element. Filters out the data and feeds them to
- * the internal variables.
+ * @brief Content of a given XML element. Filters out the data and feeds them to
+ *        the internal variables.
  *
- * \param str XML element string
+ * @param str XML element content string
  */
 void BMWStartupHandler::OnCharacters(const char *str)
 {
@@ -221,26 +226,22 @@ void BMWStartupHandler::OnCharacters(const char *str)
   }
 }
 
-//--------------------------------------------------------------------------
-// OnComment
 //--------------------------------------------------------------------------
 /**
- * <p>Called when a XML comment is found. Not used.
+ * @brief Called when an XML comment is found. Not used.
  *
- * \param str not used.
+ * @param str Comment string (not used)
  */
 void BMWStartupHandler::OnComment(const char *str)
 {
   // nothing to be done for now
 }
 
-//--------------------------------------------------------------------------
-// OnWarning
 //--------------------------------------------------------------------------
 /**
- * <p>Called when the XML parser emits a warning.
+ * @brief Called when the XML parser emits a warning.
  *
- * \param str warning string
+ * @param str Warning string
  */
 void BMWStartupHandler::OnWarning(const char *str)
 {
@@ -248,13 +249,11 @@ void BMWStartupHandler::OnWarning(const char *str)
   std::cerr << std::endl;
 }
 
-//--------------------------------------------------------------------------
-// OnError
 //--------------------------------------------------------------------------
 /**
- * <p>Called when the XML parser emits an error.
+ * @brief Called when the XML parser emits an error.
  *
- * \param str error string
+ * @param str Error string
  */
 void BMWStartupHandler::OnError(const char *str)
 {
@@ -262,13 +261,11 @@ void BMWStartupHandler::OnError(const char *str)
   std::cerr << std::endl;
 }
 
-//--------------------------------------------------------------------------
-// OnFatalError
 //--------------------------------------------------------------------------
 /**
- * <p>Called when the XML parser emits a fatal error.
+ * @brief Called when the XML parser emits a fatal error.
  *
- * \param str fatal error string
+ * @param str Fatal error string
  */
 void BMWStartupHandler::OnFatalError(const char *str)
 {
@@ -276,26 +273,25 @@ void BMWStartupHandler::OnFatalError(const char *str)
   std::cerr << std::endl;
 }
 
-//--------------------------------------------------------------------------
-// OnCdataBlock
 //--------------------------------------------------------------------------
 /**
- * <p>Not used.
+ * @brief Called when an XML CDATA block is encountered. Not used.
  *
- * \param str not used
- * \param len not used
+ * @param str CDATA content (not used)
+ * @param len Length of CDATA (not used)
  */
 void BMWStartupHandler::OnCdataBlock(const char *str, int len)
 {
   // nothing to be done for now
 }
 
-//--------------------------------------------------------------------------
-// CheckList
 //--------------------------------------------------------------------------
 /**
- * <p>Check if the default lists are present and if not, feed them with some default settings
+ * @brief Check if the default lists are present and if not, feed them with some default settings.
  *
+ * This method validates all configuration parameters and assigns sensible defaults for any
+ * parameters that were not specified in the XML file. It handles different modes (LF, LEM, Vortex)
+ * and ensures that all required parameters are properly initialized.
  */
 void BMWStartupHandler::CheckLists()
 {