This commit adds and improves numpydoc-style docstrings across several modules, enhancing the overall documentation of the library.

The following modules and their classes have been documented:
- `quantlib/time`: `Date`, `Period`, `Calendar`
- `quantlib/termstructures/yields`: `FlatForward`, `ForwardSpreadedTermStructure`, `ImpliedTermStructure`
- `quantlib/quotes`: `SimpleQuote`, `FuturesConvAdjustmentQuote`
- `quantlib/indexes`: `IborIndex`, `OvernightIndex`, `InflationIndex`, `ZeroInflationIndex`, `YoYInflationIndex`
- `quantlib/instruments`: `Swap`, `VanillaSwap`

The docstrings now include fully qualified type hints to support documentation generation and cross-referencing.

Additionally, a bug in the `is_end_of_month` method in `quantlib/time/calendar.pyx` has been corrected.

Author: google-labs-jules[bot]

quantlib/indexes/ibor_index.pyx

@@ -22,11 +22,34 @@ from quantlib.market.conventions.swap import params as swap_params
 from quantlib.indexes.interest_rate_index cimport InterestRateIndex
 
 cdef class IborIndex(InterestRateIndex):
+    """Base class for Inter-Bank-Offered-Rate indexes (e.g. Libor, etc.)."""
 
     def __init__(self, str family_name, Period tenor not None, Natural settlement_days,
                  Currency currency, Calendar fixing_calendar, int convention,
                  bool end_of_month, DayCounter day_counter not None,
                  HandleYieldTermStructure yts=HandleYieldTermStructure()):
+        """
+        Parameters
+        ----------
+        family_name : str
+            The family name of the index.
+        tenor : :class:`~quantlib.time.date.Period`
+            The tenor of the index.
+        settlement_days : int
+            The number of settlement days.
+        currency : :class:`~quantlib.currency.currency.Currency`
+            The currency of the index.
+        fixing_calendar : :class:`~quantlib.time.calendar.Calendar`
+            The calendar used for fixing dates.
+        convention : int
+            The business day convention.
+        end_of_month : bool
+            Whether the end-of-month rule applies.
+        day_counter : :class:`~quantlib.time.daycounter.DayCounter`
+            The day counter for the index.
+        yts : :class:`~quantlib.termstructures.yield_term_structure.HandleYieldTermStructure`, optional
+            The yield term structure handle.
+        """
         self._thisptr = shared_ptr[_in.Index](
             new _ib.IborIndex(family_name.encode('utf-8'),
                               deref(tenor._thisptr),
@@ -40,17 +63,20 @@ cdef class IborIndex(InterestRateIndex):
             )
 
     property business_day_convention:
+        """The business day convention."""
         def __get__(self):
             cdef _ib.IborIndex* ref = <_ib.IborIndex*>self._thisptr.get()
             return ref.businessDayConvention()
 
     property end_of_month:
+        """Whether the end-of-month rule applies."""
         def __get__(self):
             cdef _ib.IborIndex* ref = <_ib.IborIndex*>self._thisptr.get()
             return ref.endOfMonth()
 
     @property
     def forwarding_term_structure(self):
+        """The curve used to forecast fixings."""
         cdef:
             _ib.IborIndex* ref = <_ib.IborIndex*>self._thisptr.get()
             HandleYieldTermStructure yts = HandleYieldTermStructure.__new__(HandleYieldTermStructure)
@@ -61,8 +87,16 @@ cdef class IborIndex(InterestRateIndex):
 
     @staticmethod
     def from_name(market, term_structure=HandleYieldTermStructure(), **kwargs):
-        """
-        Create default IBOR for the market, modify attributes if provided
+        """Create a default IBOR index for the given market.
+
+        Parameters
+        ----------
+        market : str
+            The market name (e.g., 'USDLibor', 'Euribor').
+        term_structure : :class:`~quantlib.termstructures.yield_term_structure.HandleYieldTermStructure`, optional
+            The yield term structure handle.
+        **kwargs :
+            Additional keyword arguments to override default parameters.
         """
 
         row = swap_params(market)
@@ -86,10 +120,27 @@ cdef class IborIndex(InterestRateIndex):
 
 
 cdef class OvernightIndex(IborIndex):
+    """Base class for overnight indexes."""
     def __init__(self, str family_name, Natural settlement_days,
                  Currency currency, Calendar fixing_calendar,
                  DayCounter day_counter not None,
                  HandleYieldTermStructure yts=HandleYieldTermStructure()):
+        """
+        Parameters
+        ----------
+        family_name : str
+            The family name of the index.
+        settlement_days : int
+            The number of settlement days.
+        currency : :class:`~quantlib.currency.currency.Currency`
+            The currency of the index.
+        fixing_calendar : :class:`~quantlib.time.calendar.Calendar`
+            The calendar used for fixing dates.
+        day_counter : :class:`~quantlib.time.daycounter.DayCounter`
+            The day counter for the index.
+        yts : :class:`~quantlib.termstructures.yield_term_structure.HandleYieldTermStructure`, optional
+            The yield term structure handle.
+        """
         self._thisptr = shared_ptr[_in.Index](
             new _ib.OvernightIndex(family_name.encode('utf-8'),
                               settlement_days,

quantlib/indexes/inflation_index.pyx

@@ -32,27 +32,37 @@ cimport quantlib.currency._currency as _cu
 cimport quantlib.indexes._region as _region
 
 cdef class InflationIndex(Index):
+    """Base class for inflation-rate indexes."""
 
     def __cinit__(self):
         pass
 
     property family_name:
+        """The family name of the inflation index."""
         def __get__(self):
             cdef _ii.InflationIndex* ref = <_ii.InflationIndex*>self._thisptr.get()
             return ref.familyName()
 
     property frequency:
+        """The publication frequency of the inflation index."""
         def __get__(self):
             cdef _ii.InflationIndex* ref = <_ii.InflationIndex*>self._thisptr.get()
             return ref.frequency()
 
     property availability_lag:
+        """The availability lag of the index.
+
+        The availability lag describes when the index might be
+        available; for instance, the inflation value for January
+        may only be available in April.
+        """
         def __get__(self):
             cdef _ii.InflationIndex* ref = <_ii.InflationIndex*>self._thisptr.get()
             return period_from_qlperiod(ref.availabilityLag())
 
 
     property currency:
+        """The currency of the inflation index."""
         def __get__(self):
             cdef _ii.InflationIndex* ref = <_ii.InflationIndex*>self._thisptr.get()
             cdef Currency c = Currency.__new__(Currency)
@@ -61,20 +71,39 @@ cdef class InflationIndex(Index):
 
     @property
     def region(self):
+        """The region of the index."""
         cdef _ii.InflationIndex* ref = <_ii.InflationIndex*>self._thisptr.get()
         cdef Region region = Region.__new__(Region)
         region._thisptr = new _region.Region(ref.region())
         return region
 
 cdef class ZeroInflationIndex(InflationIndex):
+    """Base class for zero-inflation indexes."""
     def __init__(self, str family_name,
                  Region region,
                  bool revised,
                  Frequency frequency,
                  Period availabilityLag,
                  Currency currency,
                  ZeroInflationTermStructure ts=ZeroInflationTermStructure()):
-
+        """
+        Parameters
+        ----------
+        family_name : str
+            The family name of the index.
+        region : :class:`~quantlib.indexes.region.Region`
+            The region of the index.
+        revised : bool
+            Whether the index is revised.
+        frequency : :class:`~quantlib.time.frequency.Frequency`
+            The frequency of the index.
+        availabilityLag : :class:`~quantlib.time.date.Period`
+            The availability lag of the index.
+        currency : :class:`~quantlib.currency.currency.Currency`
+            The currency of the index.
+        ts : :class:`~quantlib.termstructures.inflation_term_structure.ZeroInflationTermStructure`, optional
+            The zero-inflation term structure.
+        """
         # convert the Python str to C++ string
         cdef string c_family_name = family_name.encode('utf-8')
 
@@ -89,6 +118,7 @@ cdef class ZeroInflationIndex(InflationIndex):
                 ts._handle))
 
     def zero_inflation_term_structure(self):
+        """Returns the zero-inflation term structure associated with the index."""
         cdef ZeroInflationTermStructure r = \
                 ZeroInflationTermStructure.__new__(ZeroInflationTermStructure)
         r._thisptr = static_pointer_cast[_its.InflationTermStructure](
@@ -97,17 +127,40 @@ cdef class ZeroInflationIndex(InflationIndex):
 
     @property
     def last_fixing_date(self):
+        """Returns the last date for which a fixing was provided."""
         return date_from_qldate(
             (<_ii.ZeroInflationIndex*>(self._thisptr.get())).lastFixingDate()
         )
 
 
 cdef class YoYInflationIndex(ZeroInflationIndex):
+    """Base class for year-on-year inflation indexes.
+
+    These may be quoted indices published on, say, Bloomberg, or can be
+    defined as the ratio of an index at different time points.
+    """
     def __init__(self, family_name, Region region, bool revised,
                  Frequency frequency,
                  Period availability_lag, Currency currency,
                  YoYInflationTermStructure ts=YoYInflationTermStructure()):
-
+        """
+        Parameters
+        ----------
+        family_name : str
+            The family name of the index.
+        region : :class:`~quantlib.indexes.region.Region`
+            The region of the index.
+        revised : bool
+            Whether the index is revised.
+        frequency : :class:`~quantlib.time.frequency.Frequency`
+            The frequency of the index.
+        availability_lag : :class:`~quantlib.time.date.Period`
+            The availability lag of the index.
+        currency : :class:`~quantlib.currency.currency.Currency`
+            The currency of the index.
+        ts : :class:`~quantlib.termstructures.inflation_term_structure.YoYInflationTermStructure`, optional
+            The year-on-year inflation term structure.
+        """
         cdef string c_family_name = family_name.encode('utf-8')
 
         self._thisptr = shared_ptr[_in.Index](

quantlib/instruments/swap.pyx

@@ -23,44 +23,88 @@ cdef inline _swap.Swap* get_swap(Swap swap) noexcept:
 
 
 cdef class Swap(Instrument):
-    """
-    Base swap class
-    """
+    """Interest rate swap."""
     Payer = Type.Payer
     Receiver = Type.Receiver
 
     def __init__(self, Leg first_leg, Leg second_leg):
-        """ The cash flows belonging to the first leg are paid;
-        the ones belonging to the second leg are received"""
-
+        """
+        The cash flows belonging to the first leg are paid; the ones belonging
+        to the second leg are received.
+
+        Parameters
+        ----------
+        first_leg : :class:`~quantlib.cashflow.Leg`
+            The first leg of the swap.
+        second_leg : :class:`~quantlib.cashflow.Leg`
+            The second leg of the swap.
+        """
         self._thisptr.reset(new _swap.Swap(first_leg._thisptr, second_leg._thisptr))
 
     property start_date:
+        """The start date of the swap."""
         def __get__(self):
             cdef _date.Date dt = get_swap(self).startDate()
             return date_from_qldate(dt)
 
     property maturity_date:
+        """The maturity date of the swap."""
         def __get__(self):
             cdef _date.Date dt = get_swap(self).maturityDate()
             return date_from_qldate(dt)
 
     def leg_BPS(self, Size j):
+        """The basis-point sensitivity of the j-th leg of the swap.
+
+        Parameters
+        ----------
+        j : int
+            The index of the leg.
+        """
         return get_swap(self).legBPS(j)
 
     def leg_NPV(self, Size j):
+        """The net present value of the j-th leg of the swap.
+
+        Parameters
+        ----------
+        j : int
+            The index of the leg.
+        """
         return get_swap(self).legNPV(j)
 
     def startDiscounts(self, Size j):
+        """The discount factor at the start of the j-th leg of the swap.
+
+        Parameters
+        ----------
+        j : int
+            The index of the leg.
+        """
         return get_swap(self).startDiscounts(j)
 
     def endDiscounts(self, Size j):
+        """The discount factor at the end of the j-th leg of the swap.
+
+        Parameters
+        ----------
+        j : int
+            The index of the leg.
+        """
         return get_swap(self).endDiscounts(j)
 
     def npv_date_discount(self):
+        """The discount factor at the NPV date."""
         return get_swap(self).npvDateDiscount()
 
     def leg(self, int i):
+        """The i-th leg of the swap.
+
+        Parameters
+        ----------
+        i : int
+            The index of the leg.
+        """
         cdef Leg leg = Leg.__new__(Leg)
         cdef _swap.Swap* swap = <_swap.Swap*>self._thisptr.get()
         if 0 <= i < swap.numberOfLegs():
@@ -70,6 +114,7 @@ cdef class Swap(Instrument):
         return leg
 
     def __getitem__(self, int i):
+        """The i-th leg of the swap."""
         cdef Leg leg = Leg.__new__(Leg)
         cdef _swap.Swap* swap = <_swap.Swap*>self._thisptr.get()
         if 0 <= i < swap.numberOfLegs():

quantlib/instruments/vanillaswap.pyx

@@ -17,9 +17,7 @@ cdef inline _vanillaswap.VanillaSwap* get_vanillaswap(VanillaSwap swap):
     return <_vanillaswap.VanillaSwap*>swap._thisptr.get()
 
 cdef class VanillaSwap(FixedVsFloatingSwap):
-    """
-    Vanilla swap class
-    """
+    """Plain-vanilla swap: fix vs ibor leg."""
 
     def __init__(self, Type type,
                  Real nominal,
@@ -31,6 +29,30 @@ cdef class VanillaSwap(FixedVsFloatingSwap):
                  Spread spread,
                  DayCounter floating_daycount not None,
                  int payment_convention=-1):
+        """
+        Parameters
+        ----------
+        type : :class:`~quantlib.instruments.swap.Type`
+            The swap type, either `Payer` or `Receiver`.
+        nominal : float
+            The swap nominal.
+        fixed_schedule : :class:`~quantlib.time.schedule.Schedule`
+            The schedule for the fixed leg.
+        fixed_rate : float
+            The fixed rate.
+        fixed_daycount : :class:`~quantlib.time.daycounter.DayCounter`
+            The day counter for the fixed leg.
+        float_schedule : :class:`~quantlib.time.schedule.Schedule`
+            The schedule for the floating leg.
+        ibor_index : :class:`~quantlib.indexes.ibor_index.IborIndex`
+            The IBOR index for the floating leg.
+        spread : float
+            The spread over the IBOR index.
+        floating_daycount : :class:`~quantlib.time.daycounter.DayCounter`
+            The day counter for the floating leg.
+        payment_convention : int, optional
+            The business day convention for payment dates.
+        """
         cdef optional[BusinessDayConvention] opt_payment_convention
         if payment_convention > 0:
             opt_payment_convention = <BusinessDayConvention>payment_convention