DOC: Improve trapz docstring (#19041)

Co-authored-by: Eric Wieser <wieser.eric@gmail.com>

1 files changed, 24 insertions, 4 deletions

diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 0bb41c270..9ed7700d2 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -4089,11 +4089,18 @@ def _trapz_dispatcher(y, x=None, dx=None, axis=None):
 
 @array_function_dispatch(_trapz_dispatcher)
 def trapz(y, x=None, dx=1.0, axis=-1):
-    """
+    r"""
     Integrate along the given axis using the composite trapezoidal rule.
 
-    Integrate `y` (`x`) along given axis.
-
+    If `x` is provided, the integration happens in sequence along its
+    elements - they are not sorted.
+    
+    Integrate `y` (`x`) along each 1d slice on the given axis, compute
+    :math:`\int y(x) dx`.
+    When `x` is specified, this integrates along the parametric curve,
+    computing :math:`\int_t y(t) dt =
+    \int_t y(t) \left.\frac{dx}{dt}\right|_{x=x(t)} dt`.
+    
     Parameters
     ----------
     y : array_like
@@ -4143,6 +4150,20 @@ def trapz(y, x=None, dx=1.0, axis=-1):
     8.0
     >>> np.trapz([1,2,3], dx=2)
     8.0
+    
+    Using a decreasing `x` corresponds to integrating in reverse:
+    
+    >>> np.trapz([1,2,3], x=[8,6,4])  
+    -8.0
+    
+    More generally `x` is used to integrate along a parametric curve.
+    This finds the area of a circle, noting we repeat the sample which closes
+    the curve:
+    
+    >>> theta = np.linspace(0, 2 * np.pi, num=1000, endpoint=True)
+    >>> np.trapz(np.cos(theta), x=np.sin(theta))
+    3.141571941375841
+
     >>> a = np.arange(6).reshape(2, 3)
     >>> a
     array([[0, 1, 2],
@@ -4151,7 +4172,6 @@ def trapz(y, x=None, dx=1.0, axis=-1):
     array([1.5, 2.5, 3.5])
     >>> np.trapz(a, axis=1)
     array([2.,  8.])
-
     """
     y = asanyarray(y)
     if x is None: