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):