DOC: document pandas.types.common

Closes pandas-devgh-15895.

Author: gfyoung

pandas/types/common.py

@@ -31,6 +31,47 @@
 
 
 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.
+
+    Examples
+    --------
+    >>> arr = np.array([1, 2, 3], dtype=np.int64)
+    >>> arr
+    array([1, 2, 3])
+    >>>
+    >>> arr.dtype
+    dtype('int64')
+    >>>
+    >>> float_arr = _ensure_float(arr)
+    >>> float_arr
+    array([ 1.,  2.,  3.])
+    >>>
+    >>> float_arr.dtype
+    dtype('float64')
+
+    If the array is not of the integer dtype, we return it as is:
+
+    >>> arr = np.array(['a', 'b', 'c'])
+    >>> arr
+    array(['a', 'b', 'c'], 
+          dtype='<U1')
+    >>>
+    >>> float_arr = _ensure_float(arr)
+    >>> float_arr
+    array(['a', 'b', 'c'], 
+          dtype='<U1')
+    """
+
     if issubclass(arr.dtype.type, (np.integer, np.bool_)):
         arr = arr.astype(float)
     return arr