DOC: NPV: Document new "broadcasting" behaviour

Author: Kai-Striega

numpy_financial/_financial.py

@@ -862,6 +862,7 @@ def _npv_native(rates, values, out, zero, one):
             out[i, j] = acc
 
 
+# We require ``forceobj=True`` here to support decimal.Decimal types
 @nb.jit(forceobj=True)
 def _npv_decimal(rates, values, out, zero, one):
     for i in range(rates.shape[0]):
@@ -938,6 +939,17 @@ def npv(rate, values):
     >>> np.round(npf.npv(rate, cashflows) + initial_cashflow, 5)
     3065.22267
 
+    The NPV calculation may be applied to several ``rates`` and ``cashflows``
+    simulatneously. This produces an array of shape
+    ``(len(rates), len(cashflows))``.
+
+    >>> rates = [0.00, 0.05, 0.10]
+    >>> cashflows = [[-4_000, 500, 800], [-5_000, 600, 900]]
+    >>> npf.npv(rates, cashflows).round(2)
+    array([[-2700.  , -3500.  ],
+           [-2798.19, -3612.24],
+           [-2884.3 , -3710.74]])
+
     """
     rates = np.atleast_1d(rate)
     values = np.atleast_2d(values)