DOC: Document pandas.core.dtypes.common

Closes pandas-devgh-15895.

Author: gfyoung

pandas/core/dtypes/common.py

@@ -82,20 +82,102 @@ def _ensure_categorical(arr):
 
 
 def is_object_dtype(arr_or_dtype):
+    """
+    Check whether an object or dtype is of the object dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like, dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    is_object_dtype : Whether or not the object or dtype is of
+                      the object dtype.
+
+    Examples
+    --------
+    >>> is_object_dtype(object)
+    True
+    >>> is_object_dtype(int)
+    False
+    >>> is_object_dtype(np.array([], dtype=object))
+    True
+    >>> is_object_dtype(np.array([], dtype=int))
+    False
+    >>> is_object_dtype([1, 2, 3])
+    False
+    """
+
     if arr_or_dtype is None:
         return False
     tipo = _get_dtype_type(arr_or_dtype)
     return issubclass(tipo, np.object_)
 
 
 def is_sparse(array):
-    """ return if we are a sparse array """
+    """
+    Check whether an array-like is a pandas sparse array.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_sparse : Whether or not the array-like is a pandas sparse array.
+
+    Examples
+    --------
+    >>> is_sparse(np.array([1, 2, 3]))
+    False
+    >>> is_sparse(pd.SparseArray([1, 2, 3]))
+    True
+    >>> is_sparse(pd.SparseSeries([1, 2, 3]))
+    True
+
+    This function checks only for pandas sparse array instances, so
+    sparse arrays from other libraries will return False.
+    >>> from scipy.sparse import bsr_matrix
+    >>> is_sparse(bsr_matrix([1, 2, 3]))
+    False
+    """
+
     return isinstance(array, (ABCSparseArray, ABCSparseSeries))
 
 
 def is_scipy_sparse(array):
-    """ return if we are a scipy.sparse.spmatrix """
+    """
+    Check whether an array-like is a scipy.sparse.spmatrix instance.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_scipy_sparse : Whether or not the array-like is a
+                      scipy.sparse.spmatrix instance.
+
+    Notes
+    -----
+    If scipy is not installed, this function will always return False.
+
+    Examples
+    --------
+    >>> from scipy.sparse import bsr_matrix
+    >>> is_scipy_sparse(bsr_matrix([1, 2, 3]))
+    True
+    >>> is_scipy_sparse(pd.SparseArray([1, 2, 3]))
+    False
+    >>> is_scipy_sparse(pd.SparseSeries([1, 2, 3]))
+    False
+    """
+
     global _is_scipy_sparse
+
     if _is_scipy_sparse is None:
         try:
             from scipy.sparse import issparse as _is_scipy_sparse
@@ -105,7 +187,31 @@ def is_scipy_sparse(array):
 
 
 def is_categorical(array):
-    """ return if we are a categorical possibility """
+    """
+    Check whether an array-like is a Categorical instance.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_categorical : Whether or not the array-like is a Categorical instance.
+
+    Examples
+    --------
+    >>> is_categorical([1, 2, 3])
+    False
+
+    Categoricals and Series Categoricals will return True.
+    >>> cat = pd.Categorical([1, 2, 3])
+    >>> is_categorical(cat)
+    True
+    >>> is_categorical(pd.Series(cat))
+    True
+    """
+
     return isinstance(array, ABCCategorical) or is_categorical_dtype(array)