style: reorder APIs in alphabetical order

Author: kgryte

src/array_api_stubs/_draft/statistical_functions.py

@@ -14,7 +14,7 @@
 from ._types import Optional, Tuple, Union, array, dtype
 
 
-def cumulative_sum(
+def cumulative_prod(
     x: array,
     /,
     *,
@@ -23,14 +23,14 @@ def cumulative_sum(
     include_initial: bool = False,
 ) -> array:
     """
-    Calculates the cumulative sum of elements in the input array ``x``.
+    Calculates the cumulative product of elements in the input array ``x``.
 
     Parameters
     ----------
     x: array
         input array. Should have a numeric data type.
     axis: Optional[int]
-        axis along which a cumulative sum must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative sum by counting from the last dimension.
+        axis along which a cumulative product must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative product by counting from the last dimension.
 
         If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required.
 
@@ -40,33 +40,31 @@ def cumulative_sum(
         -   if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type.
         -   if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type).
 
-        If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``.
+        If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the product (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``.
 
     include_initial: bool
-        boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the additive identity (i.e., zero). Default: ``False``.
+        boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the multiplicative identity (i.e., one). Default: ``False``.
 
     Returns
     -------
     out: array
-        an array containing the cumulative sums. The returned array must have a data type as described by the ``dtype`` parameter above.
+        an array containing the cumulative products. The returned array must have a data type as described by the ``dtype`` parameter above.
 
-        Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules:
+        Let ``N`` be the size of the axis along which to compute the cumulative product. The returned array must have a shape determined according to the following rules:
 
-        -   if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``.
+        -   if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative product must be ``N+1``.
         -   if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``.
 
     Notes
     -----
 
     **Special Cases**
 
-    For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`.
-
-    .. versionadded:: 2023.12
+    For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.multiply`.
     """
 
 
-def cumulative_prod(
+def cumulative_sum(
     x: array,
     /,
     *,
@@ -75,14 +73,14 @@ def cumulative_prod(
     include_initial: bool = False,
 ) -> array:
     """
-    Calculates the cumulative product of elements in the input array ``x``.
+    Calculates the cumulative sum of elements in the input array ``x``.
 
     Parameters
     ----------
     x: array
         input array. Should have a numeric data type.
     axis: Optional[int]
-        axis along which a cumulative product must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative product by counting from the last dimension.
+        axis along which a cumulative sum must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative sum by counting from the last dimension.
 
         If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required.
 
@@ -92,27 +90,29 @@ def cumulative_prod(
         -   if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type.
         -   if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type).
 
-        If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the product (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``.
+        If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum (rationale: the ``dtype`` keyword argument is intended to help prevent overflows). Default: ``None``.
 
     include_initial: bool
-        boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the multiplicative identity (i.e., one). Default: ``False``.
+        boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the additive identity (i.e., zero). Default: ``False``.
 
     Returns
     -------
     out: array
-        an array containing the cumulative products. The returned array must have a data type as described by the ``dtype`` parameter above.
+        an array containing the cumulative sums. The returned array must have a data type as described by the ``dtype`` parameter above.
 
-        Let ``N`` be the size of the axis along which to compute the cumulative product. The returned array must have a shape determined according to the following rules:
+        Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules:
 
-        -   if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative product must be ``N+1``.
+        -   if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``.
         -   if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``.
 
     Notes
     -----
 
     **Special Cases**
 
-    For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.multiply`.
+    For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`.
+
+    .. versionadded:: 2023.12
     """