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

PR-URL: #939
Ref: #397

Author: kgryte

src/array_api_stubs/_draft/sorting_functions.py

@@ -10,24 +10,26 @@ def argsort(
     """
     Returns the indices that sort an array ``x`` along a specified axis.
 
-    .. note::
-       For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
-
     Parameters
     ----------
-    x : array
-        input array. Should have a real-valued data type.
+    x: array
+        input array. **Should** have a real-valued data type.
     axis: int
-        axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``.
+        axis along which to sort. 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``.
     descending: bool
-        sort order. If ``True``, the returned indices sort ``x`` in descending order (by value). If ``False``, the returned indices sort ``x`` in ascending order (by value). Default: ``False``.
+        sort order. If ``True``, the returned indices **must** sort ``x`` in descending order (by value). If ``False``, the returned indices **must** sort ``x`` in ascending order (by value). Default: ``False``.
     stable: bool
-        sort stability. If ``True``, the returned indices must maintain the relative order of ``x`` values which compare as equal. If ``False``, the returned indices may or may not maintain the relative order of ``x`` values which compare as equal (i.e., the relative order of ``x`` values which compare as equal is implementation-dependent). Default: ``True``.
+        sort stability. If ``True``, the returned indices **must** maintain the relative order of ``x`` values which compare as equal. If ``False``, the returned indices **may** maintain the relative order of ``x`` values which compare as equal (i.e., the relative order of ``x`` values which compare as equal is implementation-dependent). Default: ``True``.
 
     Returns
     -------
-    out : array
-        an array of indices. The returned array must have the same shape as ``x``. The returned array must have the default array index data type.
+    out: array
+        an array of indices. The returned array **must** have the same shape as ``x``. The returned array **must** have the default array index data type.
+
+    Notes
+    -----
+
+    -  For backward compatibility, conforming implementations **may** support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
     """
 
 
@@ -37,22 +39,24 @@ def sort(
     """
     Returns a sorted copy of an input array ``x``.
 
-    .. note::
-       For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
-
     Parameters
     ----------
     x: array
-        input array. Should have a real-valued data type.
+        input array. **Should** have a real-valued data type.
     axis: int
-        axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``.
+        axis along which to sort. 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``.
     descending: bool
-        sort order. If ``True``, the array must be sorted in descending order (by value). If ``False``, the array must be sorted in ascending order (by value). Default: ``False``.
+        sort order. If ``True``, the array **must** be sorted in descending order (by value). If ``False``, the array **must** be sorted in ascending order (by value). Default: ``False``.
     stable: bool
-        sort stability. If ``True``, the returned array must maintain the relative order of ``x`` values which compare as equal. If ``False``, the returned array may or may not maintain the relative order of ``x`` values which compare as equal (i.e., the relative order of ``x`` values which compare as equal is implementation-dependent). Default: ``True``.
+        sort stability. If ``True``, the returned array **must** maintain the relative order of ``x`` values which compare as equal. If ``False``, the returned array **may** maintain the relative order of ``x`` values which compare as equal (i.e., the relative order of ``x`` values which compare as equal is implementation-dependent). Default: ``True``.
 
     Returns
     -------
-    out : array
-        a sorted array. The returned array must have the same data type and shape as ``x``.
+    out: array
+        a sorted array. The returned array **must** have the same data type and shape as ``x``.
+
+    Notes
+    -----
+
+    -   For backward compatibility, conforming implementations **may** support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
     """