Add Doxygen documentation for LS regression and parametric exercise

ql/methods/montecarlo/genericlsregression.hpp

@@ -25,15 +25,28 @@
 
 namespace QuantLib {
 
-    //! returns the biased estimate obtained while regressing
-    /* TODO document:
-       n exercises, n+1 elements in simulationData
-       simulationData[0][j] -> cashflows up to first exercise, j-th path
-       simulationData[i+1][j] -> i-th exercise, j-th path
-
-       simulationData[0][j].foo unused (unusable?) if foo != cumulatedCashFlows
-
-       basisCoefficients.size() = n
+    /*! Estimates the value of early-exercise rights using the
+        Longstaff-Schwartz least-squares regression method.
+
+        Returns the biased estimate of the option value obtained
+        by regressing continuation values against basis functions
+        along each simulated path.
+
+        \param simulationData collected node data for all paths and
+               exercise dates. It must contain n+1 elements
+               for n exercise dates:
+               - simulationData[0][j] holds the cash flows
+                 accumulated up to the first exercise date on the
+                 j-th path (only the \c cumulatedCashFlows
+                 field is used);
+               - simulationData[i+1][j] holds the data at
+                 the i-th exercise date on the j-th
+                 path.
+
+        \param basisCoefficients output parameter. After the call, it
+               contains the regression coefficients for each exercise
+               date; its size must equal the number of exercise dates
+               \c n.
     */
     Real genericLongstaffSchwartzRegression(
         std::vector<std::vector<NodeData> >& simulationData,

ql/methods/montecarlo/parametricexercise.hpp

@@ -26,29 +26,44 @@
 
 namespace QuantLib {
 
+    //! Abstract interface for a parametric early-exercise strategy.
+    /*! Derived classes encode a family of exercise boundaries
+        parameterized by a set of real-valued parameters.  The
+        optimal parameters are found by numerical optimization
+        (see genericEarlyExerciseOptimization()).
+    */
     class ParametricExercise {
       public:
         virtual ~ParametricExercise() = default;
-        // possibly different for each exercise
+        //! number of state variables used at each exercise date
         virtual std::vector<Size> numberOfVariables() const = 0;
+        //! number of free parameters at each exercise date
         virtual std::vector<Size> numberOfParameters() const = 0;
+        /*! returns true if exercise is optimal given \p parameters
+        and the state \p variables at \p exerciseNumber */
         virtual bool exercise(Size exerciseNumber,
                               const std::vector<Real>& parameters,
                               const std::vector<Real>& variables) const = 0;
+        //! provides an initial guess for the parameters
         virtual void guess(Size exerciseNumber,
                            std::vector<Real>& parameters) const = 0;
     };
 
 
-    //! returns the biased estimate obtained while optimizing
-    /* TODO document:
-       n exercises, n+1 elements in simulationData
-       simulationData[0][j] -> cashflows up to first exercise, j-th path
-       simulationData[i+1][j] -> i-th exercise, j-th path
+    /*! Estimates the value of early-exercise rights
+        by optimizing a parametric exercise strategy.
 
-       simulationData[0][j].foo unused (unusable?) if foo != cumulatedCashFlows
+        Returns a biased estimate of the option value
+        by maximizing the strategy value over parameters at each exercise date.
 
-       parameters.size() = n
+        \param simulationData Node data for all paths and exercise dates.
+                              Contains n+1 elements for n exercise dates
+                              - simulationData[0][j]: accumulated cash flows on path j
+                              - simulationData[i+1][j]: data at exercise date i on path j
+        \param exercise Parametric exercise strategy to optimize
+        \param parameters Output: optimal parameters for each exercise date (size = n)
+        \param endCriteria Convergence criteria for the optimizer
+        \param method Optimization algorithm
     */
     Real genericEarlyExerciseOptimization(
         std::vector<std::vector<NodeData> >& simulationData,