DOC: document pandas.types.common

Closes pandas-devgh-15895.

Author: gfyoung

pandas/types/common.py

@@ -31,6 +31,19 @@
 
 
 def _ensure_float(arr):
+    """
+    Ensure that an array object has a float dtype if possible.
+
+    Parameters
+    ----------
+    arr : The array whose data type we want to enforce as float.
+
+    Returns
+    -------
+    float_arr : The original array cast to the float dtype if
+                possible. Otherwise, the original array is returned.
+    """
+
     if issubclass(arr.dtype.type, (np.integer, np.bool_)):
         arr = arr.astype(float)
     return arr
@@ -46,6 +59,19 @@ def _ensure_float(arr):
 
 
 def _ensure_categorical(arr):
+    """
+    Ensure that an array object is a Categorical (if not already).
+
+    Parameters
+    ----------
+    arr : The array that we want to convert into a Categorical.
+
+    Returns
+    -------
+    cat_arr : The original array cast as a Categorical. If it already
+              is a Categorical, we return as is.
+    """
+
     if not is_categorical(arr):
         from pandas import Categorical
         arr = Categorical(arr)
@@ -220,10 +246,21 @@ def is_datetime_or_timedelta_dtype(arr_or_dtype):
 
 def _is_unorderable_exception(e):
     """
-    return a boolean if we an unorderable exception error message
+    Check if the exception raised is an unorderable exception.
 
-    These are different error message for PY>=3<=3.5 and PY>=3.6
+    The error message differs for 3 <= PY <= 3.5 and PY >= 3.6, so
+    we need to condition based on Python version.
+
+    Parameters
+    ----------
+    e : The error message to check.
+
+    Returns
+    -------
+    is_orderable_exc : Whether or not the exception raised is an
+                       unorderable exception.
     """
+
     if PY36:
         return "'>' not supported between instances of" in str(e)
 
@@ -346,7 +383,22 @@ def is_complex_dtype(arr_or_dtype):
 
 
 def _coerce_to_dtype(dtype):
-    """ coerce a string / np.dtype to a dtype """
+    """
+    Coerce a string or np.dtype to a pandas or numpy
+    dtype if possible.
+
+    If we cannot convert to a pandas dtype initially,
+    we convert to a numpy dtype.
+
+    Parameters
+    ----------
+    dtype : The dtype that we want to coerce.
+
+    Returns
+    -------
+    pd_or_np_dtype : The coerced dtype.
+    """
+
     if is_categorical_dtype(dtype):
         dtype = CategoricalDtype()
     elif is_datetime64tz_dtype(dtype):
@@ -359,8 +411,27 @@ def _coerce_to_dtype(dtype):
 
 
 def _get_dtype(arr_or_dtype):
+    """
+    Get the dtype instance associated with an array
+    or dtype object.
+
+    Parameters
+    ----------
+    arr_or_dtype : The array-like or dtype object
+                   whose dtype we want to extract.
+
+    Returns
+    -------
+    obj_dtype : The extract dtype instance from the
+                passed in array or dtype object.
+
+    Raises
+    ------
+    TypeError : The passed in object is None.
+    """
+
     if arr_or_dtype is None:
-        raise TypeError
+        raise TypeError("Cannot deduce dtype from null object")
     if isinstance(arr_or_dtype, np.dtype):
         return arr_or_dtype
     elif isinstance(arr_or_dtype, type):
@@ -385,6 +456,21 @@ def _get_dtype(arr_or_dtype):
 
 
 def _get_dtype_type(arr_or_dtype):
+    """
+    Get the type (NOT dtype) instance associated with
+    an array or dtype object.
+
+    Parameters
+    ----------
+    arr_or_dtype : The array-like or dtype object
+                   whose type we want to extract.
+
+    Returns
+    -------
+    obj_type : The extract type instance from the
+               passed in array or dtype object.
+    """
+
     if isinstance(arr_or_dtype, np.dtype):
         return arr_or_dtype.type
     elif isinstance(arr_or_dtype, type):