improve the doxygen docu of PUserFcn.* and PUserFcnBase.*

src/classes/PUserFcnBase.cpp

@@ -34,21 +34,58 @@
 
 ClassImp(PUserFcnBase)
 
-//--------------------------------------------------------------------------
-// This function is a replacement for the ParseFile method of TSAXParser.
-// It is needed because in certain environments ParseFile does not work but ParseBuffer does.
 //--------------------------------------------------------------------------
 /**
- * <p> Replacement for the ParseFile method of TSAXParser
- *     that can be used in user functions.
+ * \brief Parses an XML file using buffer-based parsing for better compatibility.
  *
- * <p><b>return:</b>
- * - 1 if file cannot be read
- * - 0 if the file has been parsed successfully
- * - parse error code otherwise
+ * This function provides a replacement for TSAXParser::ParseFile() that works
+ * reliably across different environments. Some systems have issues with direct
+ * file parsing, but buffer-based parsing (ParseBuffer) works consistently.
  *
- * \param saxParser pointer to a TSAXParser object
- * \param startup_path_name full path to the XML file to be read
+ * \section parsexml_usage Usage in User Functions
+ *
+ * User functions that need to read XML configuration files should use this
+ * function instead of TSAXParser::ParseFile():
+ *
+ * \code{.cpp}
+ * class TMyConfigurableFcn : public PUserFcnBase {
+ *   private:
+ *     MyConfigHandler fHandler;  // Derived from TSAXParser callbacks
+ *
+ *   public:
+ *     Bool_t LoadConfig(const char* configFile) {
+ *         TSAXParser parser;
+ *         parser.ConnectToHandler("MyConfigHandler", &fHandler);
+ *
+ *         Int_t status = parseXmlFile(&parser, configFile);
+ *         if (status != 0) {
+ *             std::cerr << "Failed to parse config: " << configFile << std::endl;
+ *             return false;
+ *         }
+ *         return true;
+ *     }
+ * };
+ * \endcode
+ *
+ * \section parsexml_algorithm Algorithm
+ *
+ * 1. Opens the file in binary mode, seeking to end
+ * 2. Determines file size from stream position
+ * 3. Allocates buffer and reads entire file
+ * 4. Passes buffer to TSAXParser::ParseBuffer()
+ * 5. Cleans up buffer memory
+ *
+ * \param saxParser Pointer to a configured TSAXParser object. The parser
+ *        should have its handler connected before calling this function.
+ * \param startup_path_name Full filesystem path to the XML file to parse.
+ *
+ * \return Status code:
+ *         - 0: Success - file parsed without errors
+ *         - 1: File error - could not open or read the file
+ *         - >1: XML parse error from TSAXParser::ParseBuffer()
+ *
+ * \see PStartupHandler for an example of XML parsing in musrfit
+ * \see TSAXParser for ROOT's SAX parser documentation
  */
 Int_t parseXmlFile(TSAXParser *saxParser, const char *startup_path_name)
 {
@@ -76,5 +113,43 @@ Int_t parseXmlFile(TSAXParser *saxParser, const char *startup_path_name)
   return status;
 }
 
-// place a void pointer vector for global user function objects which might be needed
+//--------------------------------------------------------------------------
+/**
+ * \brief Global storage for user function objects requiring persistent state.
+ *
+ * This vector provides a global container for user functions that need to
+ * maintain state across multiple evaluations or share data between runs.
+ * It is primarily used by user functions implementing the "global part"
+ * interface (NeedGlobalPart(), SetGlobalPart(), GlobalPartIsValid()).
+ *
+ * \section gGlobalUserFcn_usage Usage Pattern
+ *
+ * User functions with expensive initialization (lookup tables, precomputed
+ * grids, loaded data files) store their global objects here:
+ *
+ * \code{.cpp}
+ * // In user function's SetGlobalPart implementation:
+ * void TMyFcn::SetGlobalPart(std::vector<void*> &globalPart, UInt_t idx) {
+ *     if (idx < globalPart.size() && globalPart[idx] != nullptr) {
+ *         fGlobal = static_cast<MyGlobalData*>(globalPart[idx]);
+ *     } else {
+ *         fGlobal = new MyGlobalData();
+ *         fGlobal->Initialize();  // Expensive one-time computation
+ *         if (idx < globalPart.size())
+ *             globalPart[idx] = fGlobal;
+ *         else
+ *             globalPart.push_back(fGlobal);
+ *     }
+ * }
+ * \endcode
+ *
+ * \note The vector stores void pointers, so user functions must cast
+ *       appropriately and manage memory for their specific data types.
+ *
+ * \warning User functions are responsible for proper cleanup of their
+ *          global objects to avoid memory leaks.
+ *
+ * \see PUserFcnBase::SetGlobalPart() for the interface to populate this vector
+ * \see PTheory for how global parts are initialized during theory setup
+ */
 std::vector<void *> gGlobalUserFcn;