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

kgryte · web-flow · commit 58d2d3cb4145 · 2025-06-12T01:29:35.000-07:00
PR-URL: #957 Ref: #397
diff --git a/src/array_api_stubs/_draft/indexing_functions.py b/src/array_api_stubs/_draft/indexing_functions.py
@@ -10,24 +10,24 @@ def take(x: array, indices: array, /, *, axis: Optional[int] = None) -> array:
     Parameters
     ----------
     x: array
-        input array. Should have one or more dimensions (axes).
+        input array. **Should** have one or more axes.
     indices: array
-        array indices. The array must be one-dimensional and have an integer data type. If an index is negative, the function must determine the element to select along a specified axis (dimension) by counting from the last element (where ``-1`` refers to the last element).
+        array indices. The array **must** be one-dimensional and have an integer data type. If an index is negative, the function **must** determine the element to select along a specified axis by counting from the last element (where ``-1`` refers to the last element).
     axis: Optional[int]
-        axis over which to select values. If ``axis`` is negative, the function must determine the axis along which to select values by counting from the last dimension (where ``-1`` refers to the last dimension).
+        axis over which to select values. If ``axis`` is negative, the function **must** determine the axis along which to select values by counting from the last axis (where ``-1`` refers to the last axis).
 
-        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.
+        If ``x`` is a one-dimensional array, providing an ``axis`` **must** be optional; however, if ``x`` has more than one axis, providing an ``axis`` **must** be required.
 
     Returns
     -------
     out: array
-        an array having the same data type as ``x``. The output array must have the same rank (i.e., number of dimensions) as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` whose size must equal the number of elements in ``indices``.
+        an array having the same data type as ``x``. The output array **must** have the same number of axes as ``x`` and **must** have the same shape as ``x``, except for the axis specified by ``axis`` whose size **must** equal the number of elements in ``indices``.
 
     Notes
     -----
 
-    -   Conceptually, ``take(x, indices, axis=3)`` is equivalent to ``x[:,:,:,indices,...]``; however, explicit indexing via arrays of indices is not currently supported in this specification due to concerns regarding ``__setitem__`` and array mutation semantics.
-    -   This specification does not require bounds checking. The behavior for out-of-bounds indices is left unspecified.
+    -   This specification does not require bounds checking. The behavior for out-of-bounds indices is unspecified and thus implementation-defined.
+
     -   When ``x`` is a zero-dimensional array, behavior is unspecified and thus implementation-defined.
 
     .. versionadded:: 2022.12
@@ -50,21 +50,21 @@ def take_along_axis(x: array, indices: array, /, *, axis: int = -1) -> array:
     Parameters
     ----------
     x: array
-        input array. Must be compatible with ``indices``, except for the axis (dimension) specified by ``axis`` (see :ref:`broadcasting`).
+        input array. **Must** be compatible with ``indices``, except for the axis specified by ``axis`` (see :ref:`broadcasting`).
     indices: array
-        array indices. Must have the same rank (i.e., number of dimensions) as ``x``. If an index is negative, the function must determine the element to select along a specified axis (dimension) by counting from the last element (where ``-1`` refers to the last element).
+        array indices. **Must** have the same number of axes as ``x`` and **must** be compatible with ``x``, except for the axis specified by ``axis`` (see :ref:`broadcasting`). If an index is negative, the function **must** determine the element to select along a specified axis by counting from the last element (where ``-1`` refers to the last element).
     axis: int
-        axis along which to select values. If ``axis`` is negative, the function must determine the axis along which to select values by counting from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``.
+        axis along which to select values. 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 the operation 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``.
 
     Returns
     -------
     out: array
-        an array having the same data type as ``x``. Must have the same rank (i.e., number of dimensions) as ``x`` and must have a shape determined according to :ref:`broadcasting`, except for the axis (dimension) specified by ``axis`` whose size must equal the size of the corresponding axis (dimension) in ``indices``.
+        an array containing elements from ``x``. The returned array **must** have the same data type as ``x``. The returned array **must** have the same number of axes as ``x`` and **must** have a shape determined according to :ref:`broadcasting`, except for the axis specified by ``axis`` whose size **must** equal the size of the corresponding axis in ``indices``.
 
     Notes
     -----
 
-    -   This specification does not require bounds checking. The behavior for out-of-bounds indices is left unspecified.
+    -   This specification does not require bounds checking. The behavior for out-of-bounds indices is unspecified and thus implementation-defined.
 
     .. versionadded:: 2024.12
     """
