DOC: timeseries.rst floating point precision (pandas-dev#15817)

Author: mchwalisz

doc/source/timeseries.rst

@@ -265,6 +265,22 @@ Typical epoch stored units
    pd.to_datetime([1349720105100, 1349720105200, 1349720105300,
                    1349720105400, 1349720105500 ], unit='ms')
 
+Conversion of float epoch times can lead to inaccurate and unexpected results.
+Python floats are unbounded precision, with about 15 significant digits (depends on
+operating system). Rounding in conversion from to high precision ``Timestamp`` is
+unavoidable. The only way to have exact precision is to use a fixed-width exact type
+(e.g. an int64).
+
+.. ipython:: python
+
+   1490195805.433502912
+
+   1490195805433502912
+
+   pd.to_datetime(1490195805.433502912, unit='s')
+
+   pd.to_datetime(1490195805433502912, unit='ns')
+
 These *work*, but the results may be unexpected.
 
 .. ipython:: python

pandas/tseries/tools.py

@@ -237,6 +237,10 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
         integer or float number. This will be based off the origin.
         Example, with unit='ms' and origin='unix' (the default), this
         would calculate the number of milliseconds to the unix epoch start.
+
+        Warning: For float arg, precision rounding might happen. To prevent
+        unexpected behavior use a fixed-width exact type.
+
     infer_datetime_format : boolean, default False
         If True and no `format` is given, attempt to infer the format of the
         datetime strings, and if it can be inferred, switch to a faster