From 84f0526cad7e4b81ca0e6895f062c6f0a0b134d6 Mon Sep 17 00:00:00 2001
From: Jeff Reback <jeff@reback.net>
Date: Tue, 26 Apr 2016 19:08:16 -0400
Subject: [PATCH] DOC: more pd.to_datetime examples

---
 doc/source/api.rst         |  1 +
 pandas/core/generic.py     |  6 ++++--
 pandas/tseries/resample.py |  2 ++
 pandas/tseries/tools.py    | 23 ++++++++++++++++++++++-
 4 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/doc/source/api.rst b/doc/source/api.rst
index b33d218bea149..9557867c252ed 100644
--- a/doc/source/api.rst
+++ b/doc/source/api.rst
@@ -1781,6 +1781,7 @@ Upsampling
    Resampler.pad
    Resampler.fillna
    Resampler.asfreq
+   Resampler.interpolate
 
 Computations / Descriptive Stats
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index 9a76a0f9443f9..788a564e3dee3 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -3446,8 +3446,6 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
             return self._constructor(new_data).__finalize__(self)
 
     _shared_docs['interpolate'] = """
-        Interpolate values according to different methods.
-
         Please note that only ``method='linear'`` is supported for
         DataFrames/Series with a MultiIndex.
 
@@ -3523,6 +3521,10 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
     @Appender(_shared_docs['interpolate'] % _shared_doc_kwargs)
     def interpolate(self, method='linear', axis=0, limit=None, inplace=False,
                     limit_direction='forward', downcast=None, **kwargs):
+        """
+        Interpolate values according to different methods.
+        """
+
         if self.ndim > 2:
             raise NotImplementedError("Interpolate has not been implemented "
                                       "on Panel and Panel 4D objects.")
diff --git a/pandas/tseries/resample.py b/pandas/tseries/resample.py
index 8814040fdddf3..a0f08a93a07d9 100644
--- a/pandas/tseries/resample.py
+++ b/pandas/tseries/resample.py
@@ -462,6 +462,8 @@ def fillna(self, method, limit=None):
     def interpolate(self, method='linear', axis=0, limit=None, inplace=False,
                     limit_direction='forward', downcast=None, **kwargs):
         """
+        Interpolate values according to different methods.
+
         .. versionadded:: 0.18.1
         """
         result = self._upsample(None)
diff --git a/pandas/tseries/tools.py b/pandas/tseries/tools.py
index ba75e4091ef9d..85867aed2c361 100644
--- a/pandas/tseries/tools.py
+++ b/pandas/tseries/tools.py
@@ -257,12 +257,33 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     1   2016-03-05
     dtype: datetime64[ns]
 
-    Date that does not meet timestamp limitations:
+    If a date that does not meet timestamp limitations, passing errors='coerce'
+    will force to NaT. Furthermore this will force non-dates to NaT as well.
 
     >>> pd.to_datetime('13000101', format='%Y%m%d')
     datetime.datetime(1300, 1, 1, 0, 0)
     >>> pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
     NaT
+
+    Passing infer_datetime_format=True can often-times speedup a parsing
+    if its not an ISO8601 format exactly, but in a regular format.
+
+    >>> s = pd.Series(['3/11/2000', '3/12/2000', '3/13/2000']*1000)
+
+    >>> s.head()
+    0    3/11/2000
+    1    3/12/2000
+    2    3/13/2000
+    3    3/11/2000
+    4    3/12/2000
+    dtype: object
+
+    >>> %timeit pd.to_datetime(s,infer_datetime_format=True)
+    100 loops, best of 3: 10.4 ms per loop
+
+    >>> %timeit pd.to_datetime(s,infer_datetime_format=False)
+    1 loop, best of 3: 471 ms per loop
+
     """
     return _to_datetime(arg, errors=errors, dayfirst=dayfirst,
                         yearfirst=yearfirst,