Functor documentation partons/core/partons#4

include/NumA/functor/multi_dimension/FunctionTypeMD.h

@@ -17,19 +17,63 @@ namespace NumA {
 /**
  * @class FunctionTypeMD
  *
- * @brief
+ * @brief Class for defining multi-dimensional functions that can be used as arguments in virtual methods.
+ * This is needed to circumvent the issue that templates and virtual methods are incompatible.
+ *
+ * Usage:
+ *
+ * ```cpp
+ * NumA::FunctionTypeMD* myFunctor = NumA::FunctorUtils::newFunctorMD(this,
+ *                                   &MyClass::myFunction);
+ * ```
+ * where `myFunction` is some function defined in some class `MyClass` with the following signature:
+ * ```cpp
+ * double MyClass::myFunction(NumA::VectorD& variables, std::vector<double>& parameters);
+ * ```
+ *
+ * The pointer `this` needs to be replaced by a pointer to the object instantiating `MyClass`, if the first line is not written inside `MyClass`.
+ *
+ * Now, you can pass `myFunctor` as argument to any method (e.g. integration routines), even virtual ones:
+ * ```cpp
+ * virtual SomeReturnType someVirtualMethod(..., NumA::FunctionTypeMD* functor, ...);
+ * ```
+ * and use the functor as a function (with the `operator()`) inside this method:
+ * ```cpp
+ * functor(variables, parameters); // parameters is optional.
+ * ```
+ *
+ * See also FunctorUtils documentation.
+ *
+ * For one dimensional functions, see FunctionType1D.
  */
 
 class FunctionTypeMD {
 public:
+    /**
+     * Empty constructor.
+     */
     FunctionTypeMD() {
     }
 
+    /**
+     * Default destructor.
+     */
     virtual ~FunctionTypeMD() {
     }
 
+    /**
+     * Operator allowing the functor to be used as a function.
+     * @param variables Multi-variate argument of the function represented by the functor.
+     * @param parameters Parameters that can be passed to the function.
+     * @return double
+     */
     virtual double operator()(VectorD &variables,
             std::vector<double> &parameters) = 0;
+    /**
+     * Operator allowing the functor to be used as a function.
+     * @param variables Multi-variate argument of the function represented by the functor.
+     * @return double
+     */
     virtual double operator()(VectorD &variables) = 0;
 };
 

include/NumA/functor/multi_dimension/FunctorMD.h

@@ -18,17 +18,27 @@ namespace NumA {
 /**
  * @class FunctorMD
  *
- * @brief Class for defining multi-dimensional functions that can be used in virtual methods.
+ * @brief Template class for defining multi-dimensional functions that can be used as arguments in virtual methods.
  * This is needed to circumvent the issue that templates and virtual methods are incompatible.
+ *
+ * See FunctionTypeMD documentation for usage.
  */
 
 template<typename PointerToObj, typename PointerToFunc>
 class FunctorMD: public FunctionTypeMD {
 public:
+    /**
+     * Constructor.
+     * @param object Pointer to an object instantiating the class where the function is defined.
+     * @param function Reference to the function.
+     */
     FunctorMD(PointerToObj* object, PointerToFunc function) :
             m_pObject(object), m_pFunction(function) {
     }
 
+    /**
+     * Default destructor.
+     */
     virtual ~FunctorMD() {
     }
 
@@ -42,14 +52,11 @@ public:
     }
 
 private:
-    PointerToObj* m_pObject;
-    PointerToFunc m_pFunction;
-
-    ////////////////////////////////////////////////////////////
-    /// Disallow copy & comparisons
-    ////////////////////////////////////////////////////////////
-    FunctorMD(const FunctorMD&); // Not implemented
-    FunctorMD& operator=(const FunctorMD&); // Not implemented
+    PointerToObj* m_pObject; ///< Pointer to an object instantiating the class where the function is defined.
+    PointerToFunc m_pFunction; ///< Reference to the function.
+
+    FunctorMD(const FunctorMD&); ///< Not implemented. Disallows copy.
+    FunctorMD& operator=(const FunctorMD&); ///< Not implemented. Disallows comparisons.
 };
 
 } // namespace NumA

include/NumA/functor/one_dimension/FunctionType1D.h

@@ -15,18 +15,62 @@ namespace NumA {
 /**
  * @class FunctionType1D
  *
- * @brief
+ * @brief Class for defining one-dimensional functions that can be used as arguments in virtual methods.
+ * This is needed to circumvent the issue that templates and virtual methods are incompatible.
+ *
+ * Usage:
+ *
+ * ```cpp
+ * NumA::FunctionType1D* myFunctor = NumA::FunctorUtils::newFunctor1D(this,
+ *                                   &MyClass::myFunction);
+ * ```
+ * where `myFunction` is some function defined in some class `MyClass` with the following signature:
+ * ```cpp
+ * double MyClass::myFunction(double variable, std::vector<double>& parameters);
+ * ```
+ *
+ * The pointer `this` needs to be replaced by a pointer to the object instantiating `MyClass`, if the first line is not written inside `MyClass`.
+ *
+ * Now, you can pass `myFunctor` as argument to any method (e.g. integration routines), even virtual ones:
+ * ```cpp
+ * virtual SomeReturnType someVirtualMethod(..., NumA::FunctionType1D* functor, ...);
+ * ```
+ * and use the functor as a function (with the `operator()`) inside this method:
+ * ```cpp
+ * functor(variable, parameters); // parameters is optional.
+ * ```
+ *
+ * See also FunctorUtils documentation.
+ *
+ * For multi-dimensional functions, see FunctionTypeMD.
  */
 
 class FunctionType1D {
 public:
+    /**
+     * Empty constructor.
+     */
     FunctionType1D() {
     }
 
+    /**
+     * Default destructor.
+     */
     virtual ~FunctionType1D() {
     }
 
+    /**
+     * Operator allowing the functor to be used as a function.
+     * @param x Argument of the function represented by the functor.
+     * @param parameters Parameters that can be passed to the function.
+     * @return double
+     */
     virtual double operator()(double x, std::vector<double> &parameters) = 0;
+    /**
+     * Operator allowing the functor to be used as a function.
+     * @param x Argument of the function represented by the functor.
+     * @return double
+     */
     virtual double operator()(double x) = 0;
 };
 

include/NumA/functor/one_dimension/Functor1D.h

@@ -17,17 +17,27 @@ namespace NumA {
 /**
  * @class Functor1D
  *
- * @brief Class for defining 1D functions that can be used in virtual methods.
+ * @brief Template class for defining one-dimensional functions that can be used as arguments in virtual methods.
  * This is needed to circumvent the issue that templates and virtual methods are incompatible.
+ *
+ * See FunctionType1D documentation for usage.
  */
 
 template<typename PointerToObj, typename PointerToFunc>
 class Functor1D: public FunctionType1D {
 public:
+    /**
+     * Constructor.
+     * @param object Pointer to an object instantiating the class where the function is defined.
+     * @param function Reference to the function.
+     */
     Functor1D(PointerToObj* object, PointerToFunc function) :
             m_pObject(object), m_pFunction(function) {
     }
 
+    /**
+     * Default destructor.
+     */
     virtual ~Functor1D() {
     }
 
@@ -40,14 +50,11 @@ public:
     }
 
 private:
-    PointerToObj* m_pObject;
-    PointerToFunc m_pFunction;
-
-    ////////////////////////////////////////////////////////////
-    /// Disallow copy & comparisons
-    ////////////////////////////////////////////////////////////
-    Functor1D(const Functor1D&); // Not implemented
-    Functor1D& operator=(const Functor1D&); // Not implemented
+    PointerToObj* m_pObject; ///< Pointer to an object instantiating the class where the function is defined.
+    PointerToFunc m_pFunction; ///< Reference to the function.
+
+    Functor1D(const Functor1D&); ///< Not implemented. Disallows copy.
+    Functor1D& operator=(const Functor1D&); ///< Not implemented. Disallows comparisons.
 };
 
 } // namespace NumA