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

src/include/PUserFcn.h

@@ -34,15 +34,79 @@
 
 #include "PUserFcnBase.h"
 
+//--------------------------------------------------------------------------------------------
 /**
- * <p>User function example class. Polynome of 3rd order.
+ * \brief Example user function implementing a third-order polynomial.
+ *
+ * PUserFcn demonstrates how to create custom theory functions by deriving
+ * from PUserFcnBase. This example implements a cubic polynomial:
+ *
+ * \f[ P(t) = a_0 + a_1 t + a_2 t^2 + a_3 t^3 \f]
+ *
+ * where \f$a_0, a_1, a_2, a_3\f$ are the polynomial coefficients passed
+ * as fit parameters.
+ *
+ * \section puserfcn_usage Usage in MSR File
+ *
+ * To use this function in your analysis:
+ *
+ * \code
+ * FITPARAMETER
+ * #  No Name       Value  Step   Pos_Error Boundaries
+ *     1 a0         1.0    0.1    none
+ *     2 a1         0.01   0.001  none
+ *     3 a2         0.001  0.0001 none
+ *     4 a3         0.0001 0.00001 none
+ *
+ * THEORY
+ * userFcn  libPUserFcn.so  PUserFcn  1 2 3 4  (a0, a1, a2, a3)
+ * \endcode
+ *
+ * \section puserfcn_applications Applications
+ *
+ * Polynomial backgrounds are useful for:
+ * - Modeling baseline drifts in long-time measurements
+ * - Phenomenological fits to slowly varying relaxation
+ * - Testing the user function infrastructure
+ *
+ * \section puserfcn_template As a Template
+ *
+ * This class serves as a minimal working example for creating custom
+ * user functions. To create your own:
+ *
+ * 1. Copy PUserFcn.h and PUserFcn.cpp
+ * 2. Rename the class and update the ClassDef/ClassImp macros
+ * 3. Implement your physics in the operator() method
+ * 4. Create a LinkDef.h and build as a shared library
+ *
+ * \see PUserFcnBase for the abstract interface and detailed implementation guide
+ * \see PTheory for how user functions are loaded and evaluated
  */
 class PUserFcn : public PUserFcnBase
 {
   public:
+    /// \brief Default constructor.
     PUserFcn();
+
+    /// \brief Destructor.
     ~PUserFcn();
 
+    /**
+     * \brief Evaluates the third-order polynomial at time t.
+     *
+     * Computes:
+     * \f[ P(t) = \texttt{param[0]} + \texttt{param[1]} \cdot t
+     *          + \texttt{param[2]} \cdot t^2 + \texttt{param[3]} \cdot t^3 \f]
+     *
+     * \param t Time value (typically in microseconds)
+     * \param param Vector of polynomial coefficients:
+     *        - param[0]: constant term \f$a_0\f$
+     *        - param[1]: linear coefficient \f$a_1\f$ (per μs)
+     *        - param[2]: quadratic coefficient \f$a_2\f$ (per μs²)
+     *        - param[3]: cubic coefficient \f$a_3\f$ (per μs³)
+     *
+     * \return The polynomial value at time t
+     */
     Double_t operator()(Double_t t, const std::vector<Double_t> &param) const;
 
   ClassDef(PUserFcn, 1)