better docstrings

Author: thrasibule

quantlib/instrument.pyx

@@ -31,9 +31,16 @@ cdef class Instrument(Observable):
             return self._thisptr.get().NPV()
 
     @property
-    def is_expired(self):
+    def is_expired(self) -> bool:
+        """whether the instrument might ave value greater than zero."""
         return self._thisptr.get().isExpired()
 
     @property
     def valuation_date(self):
+        """the date the net present value refers to.
+
+        Returns
+        -------
+        valuation_date: :class:`~quantlib.time.date.Date`
+        """
         return date_from_qldate(self._thisptr.get().valuationDate())

quantlib/instruments/bond.pyx

@@ -109,7 +109,7 @@ cdef class Bond(Instrument):
 
     @property
     def cashflows(self):
-        """ cash flow stream as a Leg """
+        """ cash flow stream as a :class:`~quantlib.cashflow.Leg`."""
         cdef Leg leg = Leg.__new__(Leg)
         leg._thisptr = self.as_ptr().cashflows()
         return leg

quantlib/option.pxd

@@ -1,9 +1,15 @@
 from quantlib.instrument cimport Instrument
 
-cdef extern from 'ql/option.hpp' namespace 'QuantLib::Option':
+cdef extern from 'ql/option.hpp' namespace 'QuantLib::Option' nogil:
     cpdef enum class OptionType "QuantLib::Option::Type":
-        Put
-        Call
+       """
+       Attributes
+       ----------
+       Put
+       Call
+       """
+       Put
+       Call
 
 
 

quantlib/pricingengines/forward/replicating_variance_swap_engine.pyx

@@ -9,19 +9,20 @@ from quantlib.pricingengines.engine cimport PricingEngine
 from ._replicating_variance_swap_engine cimport ReplicatingVarianceSwapEngine as _ReplicatingVarianceSwapEngine
 
 cdef class ReplicatingVarianceSwapEngine(PricingEngine):
-    """
-        Variance-swap pricing engine using replicating cost,
-        as described in Demeterfi, Derman, Kamal & Zou,
-        "A Guide to Volatility and Variance Swaps", 1999
-
-        Attributes
-        ---------
-        process : :obj:`GeneralizedBlackScholesProcess`
-        call_strikes : list of :obj:`Real`
-        put_strikes : list of :obj:`Real`
-        dk : Real
-            5.0
+    """Variance-swap pricing engine using replicating cost
+
+       as described in [1]_.
+
+       Parameters
+       ----------
+       process : :class:`~quantlib.processes.black_scholes_process.GeneralizedBlackScholesProcess`
+       call_strikes : list of :obj:`Real`
+       put_strikes : list of :obj:`Real`
+       dk : Real, default 5.0
 
+       References
+       ----------
+       .. [1] Demeterfi, Derman, Kamal & Zou, "A Guide to Volatility and Variance Swaps", 1999
 
     """
 

quantlib/termstructures/volatility/equityfx/local_vol_surface.pyx

@@ -13,15 +13,23 @@ cdef class LocalVolSurface(LocalVolTermStructure):
     def __init__(self, BlackVolTermStructure black_ts, HandleYieldTermStructure risk_free_ts, HandleYieldTermStructure dividend_ts, Quote underlying):
         """ Local volatility surface derived from a Black vol surface
 
-        For details about this implementation refer to [Gat]_.
-
         Parameters
         ----------
         black_ts : BlackVolTermStructure
         risk_free_ts : YieldTermStructure
-        dividend_ts : YieldTermStructure, the dividend term structure.
-        underlying : Quote, the spot underlying
+        dividend_ts : YieldTermStructure
+            the dividend term structure.
+        underlying : Quote
+            the spot underlying.
 
+
+        Notes
+        -----
+        For details about this implementation refer to [Gat]_.
+
+
+        References
+        ----------
         .. [Gat] "Stochastic Volatility and LocalVolatility" in *Case Studies and Financial Modelling Course Notes,* Jim Gatheral, Fall Term, 2003 https://web.math.ku.dk/~rolf/teaching/ctff03/Gatheral.1.pdf
         """
         self._thisptr.reset(

quantlib/time/frequency.pxd

@@ -2,19 +2,50 @@ from libcpp.string cimport string
 
 cdef extern from 'ql/time/frequency.hpp' namespace "QuantLib" nogil:
     cpdef enum Frequency:
-        NoFrequency      = -1 # null frequency
-        Once             = 0  # only once, e.g., a zero-coupon
-        Annual           = 1  # once a year
-        Semiannual       = 2  # twice a year
-        EveryFourthMonth = 3  # every fourth month
-        Quarterly        = 4  # every third month
-        Bimonthly        = 6  # every second month
-        Monthly          = 12 # once a month
-        EveryFourthWeek  = 13 # every fourth week
-        Biweekly         = 26 # every second week
-        Weekly           = 52 # once a week
-        Daily            = 365 # once a day
-        OtherFrequency   = 999 # some other unknown frequency
+        """Frequency of events
+
+        Attributes
+        ----------
+        NoFrequency
+            null frequency
+        Once
+            only once, e.g., a zero-coupon
+        Annual
+            once a year
+        Semiannual
+            twice a year
+        EveryFourthMonth
+            every fourth month
+        Quarterly
+            every third month
+        Bimonthly
+            every second month
+        Monthly
+            once a month
+        EveryFourthWeek
+            every fourth week
+        Biweekly
+            every second week
+        Weekly
+            once a week
+        Daily
+            once a day
+        OtherFrequency
+            some other unknown frequency
+        """
+        NoFrequency
+        Once
+        Annual
+        Semiannual
+        EveryFourthMonth
+        Quarterly
+        Bimonthly
+        Monthly
+        EveryFourthWeek
+        Biweekly
+        Weekly
+        Daily
+        OtherFrequency
 
 cdef extern from "<sstream>" namespace "std":
     cdef cppclass stringstream: