Added box example and removed M and Y units due to depracation

Author: ryankarlos

pandas/core/tools/timedeltas.py

@@ -20,16 +20,16 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'):
     """
     Convert argument to timedelta.
 
-    Timedeltas are differences in times, expressed in difference units
-    e.g. days, hours, minutes, seconds. This method converts an argument
+    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
           The argument which needs to be converted to timedelta.
-    unit : Integer or float
-          Denotes the unit (Y,M,D,h,m,s,ms,us,ns) of the arg.
+    unit : Integer or float, default ns
+          Denotes the unit (D,h,m,s,ms,us,ns) of the arg.
     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
@@ -69,8 +69,6 @@ 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)
 
-    For `M` and `Y` units, `1M = 30D` and 1Y = 365D:
-
     >>> pd.to_timedelta(np.arange(5), unit='M')
     TimedeltaIndex([  '0 days 00:00:00',  '30 days 10:29:06',
                       '60 days 20:58:12', '91 days 07:27:18',
@@ -82,8 +80,13 @@ def to_timedelta(arg, unit='ns', box=True, errors='raise'):
                 '1460 days 23:16:48'],
                dtype='timedelta64[ns]', freq=None)
 
+    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]')
+
     Add new column of dates from existing dates in a `DataFrame`
-    using `timedelta`
+    using `timedelta`:
 
     >>> Dates = pd.to_datetime(['26/10/2018','28/10/2018', '2/11/2018'])
     >>> df = pd.DataFrame({'Start': Dates,'Days':[5, 10, 5]})