DOC: Fixed timedelta docstring and examples

pandas/core/tools/timedeltas.py

@@ -16,31 +16,43 @@
 
 def to_timedelta(arg, unit='ns', box=True, errors='raise'):
     """
-    Convert argument to timedelta
+    Convert argument to timedelta.
+
+    Timedeltas are absolute differences in times, expressed in difference
+    units (e.g. days, hours, minutes, seconds). This method converts
+    an argument from a recognized timedelta format / value into
+    a Timedelta type.
 
     Parameters
     ----------
-    arg : string, timedelta, list, tuple, 1-d array, or Series
-    unit : str, optional
-        Denote the unit of the input, if input is an integer. Default 'ns'.
-        Possible values:
-        {'Y', 'M', 'W', 'D', 'days', 'day', 'hours', hour', 'hr', 'h',
-        'm', 'minute', 'min', 'minutes', 'T', 'S', 'seconds', 'sec', 'second',
-        'ms', 'milliseconds', 'millisecond', 'milli', 'millis', 'L',
-        'us', 'microseconds', 'microsecond', 'micro', 'micros', 'U',
-        'ns', 'nanoseconds', 'nano', 'nanos', 'nanosecond', 'N'}
-    box : boolean, default True
-        - If True returns a Timedelta/TimedeltaIndex of the results
-        - if False returns a np.timedelta64 or ndarray of values of dtype
-          timedelta64[ns]
+    arg : str, timedelta, list-like or Series
+        The data to be converted to timedelta.
+    unit : str, default 'ns'
+        Denotes the unit of the arg. Possible values:
+        ('Y', 'M', 'W', 'D', 'days', 'day', 'hours', hour', 'hr',
+        'h', 'm', 'minute', 'min', 'minutes', 'T', 'S', 'seconds',
+        'sec', 'second', 'ms', 'milliseconds', 'millisecond',
+        'milli', 'millis', 'L', 'us', 'microseconds', 'microsecond',
+        'micro', 'micros', 'U', 'ns', 'nanoseconds', 'nano', 'nanos',
+        'nanosecond', 'N').
+    box : bool, default True
+        - If True returns a Timedelta/TimedeltaIndex of the results.
+        - If False returns a numpy.timedelta64 or numpy.darray of
+          values of dtype timedelta64[ns].
     errors : {'ignore', 'raise', 'coerce'}, default 'raise'
-        - If 'raise', then invalid parsing will raise an exception
-        - If 'coerce', then invalid parsing will be set as NaT
-        - If 'ignore', then invalid parsing will return the input
+        - If 'raise', then invalid parsing will raise an exception.
+        - If 'coerce', then invalid parsing will be set as NaT.
+        - If 'ignore', then invalid parsing will return the input.
 
     Returns
     -------
-    ret : timedelta64/arrays of timedelta64 if parsing succeeded
+    timedelta64 or numpy.array of timedelta64
+        Output type returned if parsing succeeded.
+
+    See also
+    --------
+    DataFrame.astype : Cast argument to a specified dtype.
+    to_datetime : Convert argument to datetime.
 
     Examples
     --------
@@ -68,10 +80,10 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'):
     TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
                    dtype='timedelta64[ns]', freq=None)
 
-    See Also
-    --------
-    pandas.DataFrame.astype : Cast argument to a specified dtype.
-    pandas.to_datetime : Convert argument to datetime.
+    Returning an ndarray by using the 'box' keyword argument:
+
+    >>> pd.to_timedelta(np.arange(5), box=False)
+    array([0, 1, 2, 3, 4], dtype='timedelta64[ns]')
     """
     unit = parse_timedelta_unit(unit)