DOC: Clarify isreal docstring for string/obj arrays (numpy#18843)

Add Notes and Examples about behavior of isreal for string and object arrays

Co-authored-by: Ross Barnowski <[email protected]>

numpy/lib/type_check.py

@@ -262,15 +262,39 @@ def isreal(x):
     out : ndarray, bool
         Boolean array of same shape as `x`.
 
+    Notes
+    -----
+    `isreal` may behave unexpectedly for string or object arrays (see examples)
+
     See Also
     --------
     iscomplex
     isrealobj : Return True if x is not a complex type.
 
     Examples
     --------
-    >>> np.isreal([1+1j, 1+0j, 4.5, 3, 2, 2j])
+    >>> a = np.array([1+1j, 1+0j, 4.5, 3, 2, 2j], dtype=complex)
+    >>> np.isreal(a)
     array([False,  True,  True,  True,  True, False])
+    
+    The function does not work on string arrays.
+
+    >>> a = np.array([2j, "a"], dtype="U")
+    >>> np.isreal(a)  # Warns about non-elementwise comparison
+    False
+    
+    Returns True for all elements in input array of ``dtype=object`` even if
+    any of the elements is complex.
+
+    >>> a = np.array([1, "2", 3+4j], dtype=object)
+    >>> np.isreal(a)
+    array([ True,  True,  True])
+    
+    isreal should not be used with object arrays
+    
+    >>> a = np.array([1+2j, 2+1j], dtype=object)
+    >>> np.isreal(a)
+    array([ True,  True])
 
     """
     return imag(x) == 0