use Claude ai to generate doxygen documentation.

src/include/PUserFcnBase.h

@@ -37,26 +37,124 @@
 
 //--------------------------------------------------------------------------------------------
 /**
- * <p>Interface class for the user function.
+ * <p>Abstract base class for user-defined theory functions.
+ *
+ * <p>PUserFcnBase enables extending musrfit with custom theory functions
+ * beyond the 33 built-in functions. Users create derived classes implementing
+ * specific physics models, compile them into shared libraries, and load them
+ * dynamically at runtime.
+ *
+ * <p><b>Use cases:</b>
+ * - Novel relaxation mechanisms not in standard library
+ * - Material-specific models (e.g., Skyrmion lattices)
+ * - Complex multi-component functions
+ * - Proprietary or experimental theory functions
+ * - Functions requiring external libraries (GSL, CUDA, etc.)
+ *
+ * <p><b>Implementation steps:</b>
+ * 1. Create a class deriving from PUserFcnBase
+ * 2. Implement operator()(t, param) with your theory
+ * 3. Optionally implement global part for heavy initialization
+ * 4. Compile to shared library (.so/.dylib/.dll)
+ * 5. Reference in MSR file THEORY block: "userFcn libMyFunc TMyFuncClass"
+ *
+ * <p><b>Example minimal implementation:</b>
+ * @code
+ * class TMyRelaxation : public PUserFcnBase {
+ *   public:
+ *     Double_t operator()(Double_t t, const std::vector<Double_t> &par) const {
+ *       // par[0] = rate, par[1] = exponent, par[2] = time shift
+ *       Double_t tt = t - par[2];
+ *       if (tt < 0) return 0.0;
+ *       return exp(-pow(par[0]*tt, par[1]));
+ *     }
+ *     ClassDef(TMyRelaxation, 1)
+ * };
+ * @endcode
+ *
+ * <p><b>Global part:</b> For expensive one-time computations (lookup tables,
+ * matrix inversions), override NeedGlobalPart(), SetGlobalPart(), and
+ * GlobalPartIsValid(). The global part is initialized once and shared across
+ * all fit iterations.
+ *
+ * <p><b>MSR file usage:</b>
+ * @code
+ * THEORY
+ * asymmetry    1
+ * userFcn  libMyRelax.so  TMyRelaxation  map1  2  0.5  (rate, expo, tshift)
+ * @endcode
  */
 class PUserFcnBase : public TObject
 {
   public:
+    /// Default constructor
     PUserFcnBase() {}
+
+    /// Virtual destructor
     virtual ~PUserFcnBase() {}
 
-    virtual Bool_t NeedGlobalPart() const { return false; } ///< if a user function needs a global part this function should return true, otherwise false (default: false)
-    virtual void SetGlobalPart(std::vector<void *> &globalPart, UInt_t idx) {} ///< if a user function is using a global part, this function is used to invoke and retrieve the proper global object
-    virtual Bool_t GlobalPartIsValid() const { return false; } ///< if a user function is using a global part, this function returns if the global object part is valid (default: false)
+    /**
+     * <p>Indicates if this function requires global initialization.
+     *
+     * <p>Override to return true if your function needs expensive one-time
+     * setup (e.g., calculating lookup tables, loading external data).
+     * The global part is computed once and reused across fit iterations.
+     *
+     * @return true if global part needed, false otherwise (default: false)
+     */
+    virtual Bool_t NeedGlobalPart() const { return false; }
 
+    /**
+     * <p>Sets up the global part of the user function.
+     *
+     * <p>Called once during initialization if NeedGlobalPart() returns true.
+     * Use this to allocate and initialize shared data structures.
+     *
+     * @param globalPart Vector of global objects (one per run)
+     * @param idx Index of this run's global object in the vector
+     */
+    virtual void SetGlobalPart(std::vector<void *> &globalPart, UInt_t idx) {}
+
+    /**
+     * <p>Checks if the global part initialized correctly.
+     *
+     * <p>Override to validate your global data structure after SetGlobalPart().
+     *
+     * @return true if global part is valid and ready, false otherwise (default: false)
+     */
+    virtual Bool_t GlobalPartIsValid() const { return false; }
+
+    /**
+     * <p>Evaluates the user function at time t (pure virtual).
+     *
+     * <p>This is the core evaluation method called for each data point
+     * during fitting. Must be implemented by derived classes.
+     *
+     * <p><b>Parameter convention:</b> The last parameter is typically the
+     * time shift. Earlier parameters are model-specific (rates, amplitudes,
+     * exponents, etc.).
+     *
+     * @param t Time in microseconds (μs)
+     * @param param Vector of function parameters (from MSR file + maps)
+     * @return Function value at time t
+     */
     virtual Double_t operator()(Double_t t, const std::vector<Double_t> &param) const = 0;
 
   ClassDef(PUserFcnBase, 1)
 };
 
 //--------------------------------------------------------------------------
-// This function is a replacement for the ParseFile method of TSAXParser.
-//--------------------------------------------------------------------------
+/**
+ * <p>XML file parser for user function configurations.
+ *
+ * <p>This function provides a replacement for TSAXParser::ParseFile with
+ * better error handling for XML configuration files used by some user
+ * functions to load parameters or settings.
+ *
+ * @param parser Pointer to TSAXParser object
+ * @param fileName Path to XML file to parse
+ * @return 0 on success, error code on failure
+ */
 Int_t parseXmlFile(TSAXParser*, const Char_t*);
 
 #endif // _PUSERFCNBASE_H_