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]>

Author: asmeurer

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.
         """

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.
     """