cleanup docstrings

Author: thrasibule

quantlib/models/equity/bates_model.pyx

@@ -4,7 +4,17 @@
 # This program is distributed in the hope that it will be useful, but WITHOUT
 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 # FOR A PARTICULAR PURPOSE.  See the license for more details.
+"""Bates stochastic-volatility model
 
+extended versions of the Heston Model for the stochastic volatility
+of an asset including jumps.
+
+References
+----------
+.. [1] A. Sepp, "Pricing European-Style Options under Jump Diffusion
+   Processes with Stochastic Volatility: Applications of Fourier Transform"
+   (https://papers.ssrn.com/sol3/papers.cfm?abstract_id=1412333)
+"""
 include '../../types.pxi'
 
 from cython.operator cimport dereference as deref
@@ -31,12 +41,6 @@ cdef class BatesModel(HestonModel):
           (self.v0, self.kappa, self.theta, self.sigma,
            self.rho, self.Lambda, self.nu, self.delta)
 
-    def process(self):
-        cdef BatesProcess process = BatesProcess.__new__(BatesProcess)
-        process._thisptr = static_pointer_cast[_sp.StochasticProcess](
-            self._thisptr.get().process())
-        return process
-
     property Lambda:
         def __get__(self):
             return (<_bm.BatesModel*> self._thisptr.get()).Lambda()

quantlib/models/equity/heston_model.pyx

@@ -62,39 +62,50 @@ cdef class HestonModelHelper(BlackCalibrationHelper):
         )
 
 cdef class HestonModel:
+    """Heston model for the stochastic volatility of an asset
 
-    def __init__(self, HestonProcess process):
+    References
+    ----------
+    Heston, Steven L., 1993. "A Closed-Form Solution for Options with Stochastic Volatility with Applications to Bond and Currency Options."  *The review of Financial Studies, Volume 6, Issue 2, 327-343.*
+   """
 
+    def __init__(self, HestonProcess process):
         self._thisptr = shared_ptr[_hm.HestonModel](
             new _hm.HestonModel(static_pointer_cast[_hp.HestonProcess](
                 process._thisptr))
         )
 
     def process(self):
+        """underlying process"""
         cdef HestonProcess process = HestonProcess.__new__(HestonProcess)
         process._thisptr = static_pointer_cast[_sp.StochasticProcess](
             self._thisptr.get().process())
         return process
 
-    property theta:
-        def __get__(self):
-            return self._thisptr.get().theta()
-
-    property kappa:
-        def __get__(self):
-            return self._thisptr.get().kappa()
-
-    property sigma:
-        def __get__(self):
-            return self._thisptr.get().sigma()
-
-    property rho:
-        def __get__(self):
-            return self._thisptr.get().rho()
-
-    property v0:
-        def __get__(self):
-            return self._thisptr.get().v0()
+    @property
+    def theta(self):
+        """variance mean reversion level"""
+        return self._thisptr.get().theta()
+
+    @property
+    def kappa(self):
+        """variance mean reversion speed"""
+        return self._thisptr.get().kappa()
+
+    @property
+    def sigma(self):
+        """volatility of the volatility"""
+        return self._thisptr.get().sigma()
+
+    @property
+    def rho(self):
+        """correlation"""
+        return self._thisptr.get().rho()
+
+    @property
+    def v0(self):
+        """spot variance"""
+        return self._thisptr.get().v0()
 
     def calibrate(self, list helpers, OptimizationMethod method, EndCriteria
                   end_criteria, Constraint constraint=Constraint(),

quantlib/models/shortrate/onefactor_model.pyx

@@ -15,28 +15,46 @@ cimport quantlib._stochastic_process as _sp
 from quantlib.stochastic_process cimport StochasticProcess1D
 
 cdef class ShortRateDynamics:
-
+    """Base class describing the short-rate dynamics"""
     @property
     def process(self):
+        """Returns the risk_neutral dynamics of the state variable"""
         cdef StochasticProcess1D sp = StochasticProcess1D.__new__(StochasticProcess1D)
         sp._thisptr = static_pointer_cast[_sp.StochasticProcess](self._thisptr.get().process())
         return sp
 
-    def variable(self, Time t, Rate r):
+    def variable(self, Time t, Rate r) -> Real:
+        """Compute state variable from short rate"""
         return self._thisptr.get().variable(t, r)
 
     def short_rate(self, Time t, Real variable):
+        """Compute short rate from state variable"""
         return self._thisptr.get().shortRate(t, variable)
 
 cdef class OneFactorModel(ShortRateModel):
 
     @property
     def dynamics(self):
+        """short-rate dynamics
+
+        Returns
+        -------
+        dynamics : :class:`~quantlib.models.shortrate.onefactor_model.ShortRateDynamics`
+        """
         cdef ShortRateDynamics dyn = ShortRateDynamics.__new__(ShortRateDynamics)
         dyn._thisptr =  (<_ofm.OneFactorModel*>self._thisptr.get()).dynamics()
         return dyn
 
 cdef class OneFactorAffineModel(OneFactorModel):
+    r"""Single-factor affine base class
+
+    Single-factor models with an analytical formula for discount bonds
+    should inherit from this class. They must then implement the functions
+    :math:`A(T,t)` and :math:`B(T,t)` such that
+
+    .. math::
+        P(t, T, r_t) = A(t, T)\exp\{-B(t, T) r_t\}.
+    """
 
     def __init__(self):
         raise ValueError('Cannot instantiate OneFactorAffineModel')

quantlib/models/shortrate/onefactormodels/hullwhite.pyx

@@ -39,7 +39,7 @@ cdef class HullWhite(Vasicek):
 
      .. warning::
         When the term structure is relinked the :math:`r_0` parameter
-        of the underlying Vasicek model is not updated:
+        of the underlying Vasicek model is not updated.
 
      """
 

quantlib/termstructures/yields/flat_forward.pyx

@@ -21,26 +21,25 @@ from quantlib.quote cimport Quote
 
 
 cdef class FlatForward(YieldTermStructure):
-    """ Flat intereste-rate curve
+    """ Flat interest-rate curve
 
     Parameters
     ----------
-
-    refererence_date: quantlib.time.date.Date or None
+    refererence_date : :class:`~quantlib.time.date.Date` or None
         Reference date used by the curve. If None, the user must provide the
         settlement days.
-    forward: quantlib.quote.Quote or float
+    forward : :class:`~quantlib.quote.Quote` | float
         The forward value used by the curve.
-    daycounter: quantlib.time.daycounter.DayCounter
+    daycounter : :class:`~quantlib.time.daycounter.DayCounter`
         The day counter used by the curve.
-    settlement_days: int
+    settlement_days : int
         The settlement days used by this curve. If a reference date is given,
         this parameter is not used.
-    calendar: quantlib.time.calendar.Calendar
+    calendar : :class:`~quantlib.time.calendar.Calendar`
         The calendar used by the curve if created with the settlement days.
-    compounding: int (default: Continuous)
+    compounding : :class:`~quantlib.compounding.Compounding`, default Compounding.Continuous
         The type of compounding used by this curve.
-    frequency: int (default: Annual)
+    frequency : :class:`~quantlib.time.frequency.Frequency`, default `Annual`
         The frequency used by this curve.
     """