Add note that cross-kind comparisons are undefined

Fixes data-apis#819.

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::
+           Comparisons 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::
+           Comparisons of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __getitem__(
@@ -651,6 +657,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::
+           Comparisons of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __index__(self: array, /) -> int:
@@ -748,6 +757,9 @@ def __invert__(self: array, /) -> array:
 
         .. note::
            Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_invert`.
+
+        .. note::
+           Comparisons of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
         """
 
     def __le__(self: array, other: Union[int, float, array], /) -> array:
@@ -772,6 +784,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::
+           Comparisons 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:
@@ -943,6 +958,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::
+           Comparisons 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

@@ -1118,6 +1118,9 @@ def equal(x1: array, x2: array, /) -> array:
     .. note::
        For discussion of complex number equality, see :ref:`complex-numbers`.
 
+    .. note::
+       Comparisons 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.
     """
@@ -1347,6 +1350,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::
+       Comparisons of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
+
     """
 
 
@@ -1368,6 +1375,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::
+       Comparisons of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
     """
 
 
@@ -1563,6 +1573,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::
+       Comparisons of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
     """
 
 
@@ -1584,6 +1597,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::
+       Comparisons of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
     """
 
 
@@ -2134,6 +2150,9 @@ def not_equal(x1: array, x2: array, /) -> array:
     .. note::
        For discussion of complex number equality, see :ref:`complex-numbers`.
 
+    .. note::
+       Comparisons 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.
     """