docs: move notes below the fold and highlight RFC 2119 keywords

PR-URL: #940

Author: kgryte

src/array_api_stubs/_draft/utility_functions.py

@@ -14,32 +14,27 @@ def all(
     """
     Tests whether all input array elements evaluate to ``True`` along a specified axis.
 
-    .. note::
-       Positive infinity, negative infinity, and NaN must evaluate to ``True``.
-
-    .. note::
-       If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) must evaluate to ``True``.
-
-    .. note::
-       If ``x`` is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test result must be ``True``.
-
     Parameters
     ----------
     x: array
         input array.
     axis: Optional[Union[int, Tuple[int, ...]]]
-        axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction must be performed over the entire array. If a tuple of integers, logical AND reductions must be performed over multiple axes. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function must raise an exception. Default: ``None``.
+        axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction **must** be performed over the entire array. If a tuple of integers, logical AND reductions **must** be performed over multiple axes. A valid ``axis`` **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an ``axis`` is specified as a negative integer, the function **must** determine the axis along which to perform a reduction by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid ``axis``, the function **must** raise an exception. Default: ``None``.
     keepdims: bool
-        If ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``.
+        If ``True``, the reduced axes **must** be included in the result as singleton dimensions, and, accordingly, the result **must** be broadcast-compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes **must not** be included in the result. Default: ``False``.
 
     Returns
     -------
     out: array
-        if a logical AND reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of ``bool``.
+        if a logical AND reduction was performed over the entire array, the returned array **must** be a zero-dimensional array containing the test result. Otherwise, the returned array **must** be a non-zero-dimensional array containing the test results. The returned array **must** have a data type of ``bool``.
 
     Notes
     -----
 
+    -   Positive infinity, negative infinity, and NaN **must** evaluate to ``True``.
+    -   If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) **must** evaluate to ``True``.
+    -   If ``x`` is an empty array or the size of the axis along which to evaluate elements is zero, the test result **must** be ``True``.
+
     .. versionchanged:: 2022.12
        Added complex data type support.
     """
@@ -55,32 +50,27 @@ def any(
     """
     Tests whether any input array element evaluates to ``True`` along a specified axis.
 
-    .. note::
-       Positive infinity, negative infinity, and NaN must evaluate to ``True``.
-
-    .. note::
-       If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) must evaluate to ``True``.
-
-    .. note::
-       If ``x`` is an empty array or the size of the axis (dimension) along which to evaluate elements is zero, the test result must be ``False``.
-
     Parameters
     ----------
     x: array
         input array.
     axis: Optional[Union[int, Tuple[int, ...]]]
-        axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction must be performed over the entire array. If a tuple of integers, logical OR reductions must be performed over multiple axes. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function must raise an exception. Default: ``None``.
+        axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction **must** be performed over the entire array. If a tuple of integers, logical OR reductions **must** be performed over multiple axes. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an ``axis`` is specified as a negative integer, the function **must** determine the axis along which to perform a reduction by counting backward from the last dimension (where ``-1`` refers to the last axis). If provided an invalid ``axis``, the function **must** raise an exception. Default: ``None``.
     keepdims: bool
-        If ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result. Default: ``False``.
+        If ``True``, the reduced axes **must** be included in the result as singleton dimensions, and, accordingly, the result **must** be broadcast-compatible with the input array (see :ref:`broadcasting`). Otherwise, if ``False``, the reduced axes **must not** be included in the result. Default: ``False``.
 
     Returns
     -------
     out: array
-        if a logical OR reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of ``bool``.
+        if a logical OR reduction was performed over the entire array, the returned array **must** be a zero-dimensional array containing the test result. Otherwise, the returned array **must** be a non-zero-dimensional array containing the test results. The returned array **must** have a data type of ``bool``.
 
     Notes
     -----
 
+    -   Positive infinity, negative infinity, and NaN **must** evaluate to ``True``.
+    -   If ``x`` has a complex floating-point data type, elements having a non-zero component (real or imaginary) **must** evaluate to ``True``.
+    -   If ``x`` is an empty array or the size of the axis along which to evaluate elements is zero, the test result **must** be ``False``.
+
     .. versionchanged:: 2022.12
        Added complex data type support.
     """
@@ -101,31 +91,31 @@ def diff(
     Parameters
     ----------
     x: array
-        input array. Should have a numeric data type.
+        input array. **Should** have a numeric data type.
     axis: int
-        axis along which to compute differences. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute differences by counting backward from the last dimension (where ``-1`` refers to the last dimension). If provided an invalid ``axis``, the function must raise an exception. Default: ``-1``.
+        axis along which to compute differences. A valid ``axis`` **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an ``axis`` is specified as a negative integer, the function **must** determine the axis along which to compute differences by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid ``axis``, the function **must** raise an exception. Default: ``-1``.
     n: int
         number of times to recursively compute differences. Default: ``1``.
     prepend: Optional[array]
-        values to prepend to a specified axis prior to computing differences. Must have the same shape as ``x``, except for the axis specified by ``axis`` which may have any size. Should have the same data type as ``x``. Default: ``None``.
+        values to prepend to a specified axis prior to computing differences. **Must** have the same shape as ``x``, except for the axis specified by ``axis`` which can have any size. **Should** have the same data type as ``x``. Default: ``None``.
     append: Optional[array]
-        values to append to a specified axis prior to computing differences. Must have the same shape as ``x``, except for the axis specified by ``axis`` which may have any size. Should have the same data type as ``x``. Default: ``None``.
+        values to append to a specified axis prior to computing differences. **Must** have the same shape as ``x``, except for the axis specified by ``axis`` which can have any size. **Should** have the same data type as ``x``. Default: ``None``.
 
     Returns
     -------
     out: array
-        an array containing the n-th differences. Should have the same data type as ``x``. Must have the same shape as ``x``, except for the axis specified by ``axis`` which must have a size determined as follows:
+        an array containing the n-th differences. **Should** have the same data type as ``x``. **Must** have the same shape as ``x``, except for the axis specified by ``axis`` which **must** have a size determined as follows:
 
         -   Let ``M`` be the number of elements along an axis specified by ``axis``.
         -   Let ``N1`` be the number of prepended values along an axis specified by ``axis``.
         -   Let ``N2`` be the number of appended values along an axis specified by ``axis``.
-        -   The final size of the axis specified by ``axis`` must be ``M + N1 + N2 - n``.
+        -   The final size of the axis specified by ``axis`` **must** be ``M + N1 + N2 - n``.
 
     Notes
     -----
 
-    -   The first-order differences are given by ``out[i] = x[i+1] - x[i]`` along a specified axis. Higher-order differences must be calculated recursively (e.g., by calling ``diff(out, axis=axis, n=n-1)``).
-    -   If a conforming implementation chooses to support ``prepend`` and ``append`` arrays which have a different data type than ``x``, behavior is unspecified and thus implementation-defined. Implementations may choose to type promote (:ref:`type-promotion`), cast ``prepend`` and/or ``append`` to the same data type as ``x``, or raise an exception.
+    -   The first-order differences are given by ``out[i] = x[i+1] - x[i]`` along a specified axis. Higher-order differences **must** be calculated recursively (e.g., by calling ``diff(out, axis=axis, n=n-1)``).
+    -   If a conforming implementation chooses to support ``prepend`` and ``append`` arrays which have a different data type than ``x``, behavior is unspecified and thus implementation-defined. Implementations **may** choose to type promote (:ref:`type-promotion`), cast ``prepend`` and/or ``append`` to the same data type as ``x``, or raise an exception.
 
     .. versionadded:: 2024.12
     """