docs: add note that cross-kind comparisons are undefined

PR-URL: #822 Closes: #819 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]>
data-apis · Oct 31, 2024 · 6d205d7 · 6d205d7
1 parent c28d3c5
commit 6d205d7
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 0 deletions.
diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py
@@ -513,6 +513,9 @@ def __eq__(self: array, other: Union[int, float, bool, array], /) -> array:
 
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.equal`.
+
+        .. note::
+           Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __float__(self: array, /) -> float:
@@ -599,6 +602,9 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater_equal`.
+
+        .. note::
+           Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __getitem__(
@@ -657,6 +663,9 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array:
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater`.
+
+        .. note::
+           Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __index__(self: array, /) -> int:
@@ -778,6 +787,9 @@ def __le__(self: array, other: Union[int, float, array], /) -> array:
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less_equal`.
+
+        .. note::
+           Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __lshift__(self: array, other: Union[int, array], /) -> array:
@@ -823,6 +835,9 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array:
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less`.
+
+        .. note::
+           Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __matmul__(self: array, other: array, /) -> array:
@@ -949,6 +964,9 @@ def __ne__(self: array, other: Union[int, float, bool, array], /) -> array:
         .. note::
            Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.not_equal`.
 
+        .. note::
+           Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
+
         .. versionchanged:: 2022.12
             Added complex data type support.
         """

diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py
@@ -1125,6 +1125,9 @@ def equal(x1: array, x2: array, /) -> array:
     .. note::
        For discussion of complex number equality, see :ref:`complex-numbers`.
 
+    .. note::
+       Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
+
     .. versionchanged:: 2022.12
        Added complex data type support.
     """
@@ -1354,6 +1357,10 @@ def greater(x1: array, x2: array, /) -> array:
     -------
     out: array
         an array containing the element-wise results. The returned array must have a data type of ``bool``.
+
+    .. note::
+       Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
+
     """
 
 
@@ -1375,6 +1382,9 @@ def greater_equal(x1: array, x2: array, /) -> array:
     -------
     out: array
         an array containing the element-wise results. The returned array must have a data type of ``bool``.
+
+    .. note::
+       Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
     """
 
 
@@ -1570,6 +1580,9 @@ def less(x1: array, x2: array, /) -> array:
     -------
     out: array
         an array containing the element-wise results. The returned array must have a data type of ``bool``.
+
+    .. note::
+       Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
     """
 
 
@@ -1591,6 +1604,9 @@ def less_equal(x1: array, x2: array, /) -> array:
     -------
     out: array
         an array containing the element-wise results. The returned array must have a data type of ``bool``.
+
+    .. note::
+       Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
     """
 
 
@@ -2141,6 +2157,9 @@ def not_equal(x1: array, x2: array, /) -> array:
     .. note::
        For discussion of complex number equality, see :ref:`complex-numbers`.
 
+    .. note::
+       Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
+
     .. versionchanged:: 2022.12
        Added complex data type support.
     """