DOC: update the isna, isnull, notna and notnull docstring (#20459)

Author: Cheukting

pandas/core/dtypes/missing.py

@@ -29,23 +29,78 @@
 
 
 def isna(obj):
-    """Detect missing values (NaN in numeric arrays, None/NaN in object arrays)
+    """
+    Detect missing values for an array-like object.
+
+    This function takes a scalar or array-like object and indictates
+    whether values are missing (``NaN`` in numeric arrays, ``None`` or ``NaN``
+    in object arrays, ``NaT`` in datetimelike).
 
     Parameters
     ----------
-    arr : ndarray or object value
-        Object to check for null-ness
+    obj : scalar or array-like
+        Object to check for null or missing values.
 
     Returns
     -------
-    isna : array-like of bool or bool
-        Array or bool indicating whether an object is null or if an array is
-        given which of the element is null.
+    bool or array-like of bool
+        For scalar input, returns a scalar boolean.
+        For array input, returns an array of boolean indicating whether each
+        corresponding element is missing.
 
-    See also
+    See Also
+    --------
+    notna : boolean inverse of pandas.isna.
+    Series.isna : Detetct missing values in a Series.
+    DataFrame.isna : Detect missing values in a DataFrame.
+    Index.isna : Detect missing values in an Index.
+
+    Examples
     --------
-    pandas.notna: boolean inverse of pandas.isna
-    pandas.isnull: alias of isna
+    Scalar arguments (including strings) result in a scalar boolean.
+
+    >>> pd.isna('dog')
+    False
+
+    >>> pd.isna(np.nan)
+    True
+
+    ndarrays result in an ndarray of booleans.
+
+    >>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]])
+    >>> array
+    array([[ 1., nan,  3.],
+           [ 4.,  5., nan]])
+    >>> pd.isna(array)
+    array([[False,  True, False],
+           [False, False,  True]])
+
+    For indexes, an ndarray of booleans is returned.
+
+    >>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None,
+    ...                           "2017-07-08"])
+    >>> index
+    DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'],
+                  dtype='datetime64[ns]', freq=None)
+    >>> pd.isna(index)
+    array([False, False,  True, False])
+
+    For Series and DataFrame, the same type is returned, containing booleans.
+
+    >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']])
+    >>> df
+         0     1    2
+    0  ant   bee  cat
+    1  dog  None  fly
+    >>> pd.isna(df)
+           0      1      2
+    0  False  False  False
+    1  False   True  False
+
+    >>> pd.isna(df[1])
+    0    False
+    1     True
+    Name: 1, dtype: bool
     """
     return _isna(obj)
 
@@ -197,24 +252,78 @@ def _isna_ndarraylike_old(obj):
 
 
 def notna(obj):
-    """Replacement for numpy.isfinite / -numpy.isnan which is suitable for use
-    on object arrays.
+    """
+    Detect non-missing values for an array-like object.
+
+    This function takes a scalar or array-like object and indictates
+    whether values are valid (not missing, which is ``NaN`` in numeric
+    arrays, ``None`` or ``NaN`` in object arrays, ``NaT`` in datetimelike).
 
     Parameters
     ----------
-    arr : ndarray or object value
-        Object to check for *not*-null-ness
+    obj : array-like or object value
+        Object to check for *not* null or *non*-missing values.
 
     Returns
     -------
-    notisna : array-like of bool or bool
-        Array or bool indicating whether an object is *not* null or if an array
-        is given which of the element is *not* null.
+    bool or array-like of bool
+        For scalar input, returns a scalar boolean.
+        For array input, returns an array of boolean indicating whether each
+        corresponding element is valid.
 
-    See also
+    See Also
+    --------
+    isna : boolean inverse of pandas.notna.
+    Series.notna : Detetct valid values in a Series.
+    DataFrame.notna : Detect valid values in a DataFrame.
+    Index.notna : Detect valid values in an Index.
+
+    Examples
     --------
-    pandas.isna : boolean inverse of pandas.notna
-    pandas.notnull : alias of notna
+    Scalar arguments (including strings) result in a scalar boolean.
+
+    >>> pd.notna('dog')
+    True
+
+    >>> pd.notna(np.nan)
+    False
+
+    ndarrays result in an ndarray of booleans.
+
+    >>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]])
+    >>> array
+    array([[ 1., nan,  3.],
+           [ 4.,  5., nan]])
+    >>> pd.notna(array)
+    array([[ True, False,  True],
+           [ True,  True, False]])
+
+    For indexes, an ndarray of booleans is returned.
+
+    >>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None,
+    ...                          "2017-07-08"])
+    >>> index
+    DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'],
+                  dtype='datetime64[ns]', freq=None)
+    >>> pd.notna(index)
+    array([ True,  True, False,  True])
+
+    For Series and DataFrame, the same type is returned, containing booleans.
+
+    >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']])
+    >>> df
+         0     1    2
+    0  ant   bee  cat
+    1  dog  None  fly
+    >>> pd.notna(df)
+          0      1     2
+    0  True   True  True
+    1  True  False  True
+
+    >>> pd.notna(df[1])
+    0     True
+    1    False
+    Name: 1, dtype: bool
     """
     res = isna(obj)
     if is_scalar(res):