requested doc changes

Author: WBare

doc/source/missing_data.rst

@@ -458,6 +458,8 @@ at the new values.
 .. _documentation: http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation
 .. _guide: http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html
 
+.. _missing_data.interp_limits:
+
 Interpolation Limits
 ^^^^^^^^^^^^^^^^^^^^
 

doc/source/whatsnew/v0.21.0.txt

@@ -24,7 +24,9 @@ New features
   <https://www.python.org/dev/peps/pep-0519/>`_ on most readers and writers (:issue:`13823`)
 - Added `__fspath__` method to :class`:pandas.HDFStore`, :class:`pandas.ExcelFile`,
   and :class:`pandas.ExcelWriter` to work properly with the file system path protocol (:issue:`13823`)
-- Added `limit_area` parameter to `DataFrame.interpolate()` method allowing further control of which NaNs are replaced (:issue:`16284`)
+- Added `limit_area` parameter to `DataFrame.interpolate()` method allowing further control of which NaNs are replaced.
+  Use `limit-area='inside'` to fill only NaNs surrounded by valid values or use `limit-area='outside'` to fill only NaNs outside the existing valid values while preserving those inside.  (:issue:`16284`)
+  Full documentation and examples are :ref:`here <missing_data.interp_limits>`.
 
 .. _whatsnew_0210.enhancements.other:
 

pandas/core/generic.py

@@ -3884,11 +3884,13 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
             Maximum number of consecutive NaNs to fill. Must be greater than 0.
         limit_direction : {'forward', 'backward', 'both'}, default 'forward'
             Consecutive NaNs will be filled in this direction.
+            
             .. versionadded:: 0.17.0
+
         limit_area : {'inside', 'outside'}, default None
+            * None: (default) no fill restriction
             * 'inside' Only fill NaNs surrounded by valid values (interpolate).
             * 'outside' Only fill NaNs outside valid values (extrapolate).
-            * None: default fill inside and outside
             .. versionadded:: 0.21.0
 
         inplace : bool, default False

pandas/core/missing.py

@@ -152,15 +152,15 @@ def _interp_limit(invalid, fw_limit, bw_limit):
     valid_limit_directions = ['forward', 'backward', 'both']
     limit_direction = limit_direction.lower()
     if limit_direction not in valid_limit_directions:
-        raise ValueError('Invalid limit_direction: expecting one of %r, got '
-                         '%r.' % (valid_limit_directions, limit_direction))
+        raise ValueError('Invalid limit_direction: expecting one of {}, got '
+                         '{}.'.format(valid_limit_directions, limit_direction))
 
     if limit_area is not None:
         valid_limit_areas = ['inside', 'outside']
         limit_area = limit_area.lower()
         if limit_area not in valid_limit_areas:
-            raise ValueError('Invalid limit_area: expecting one of %r, got %r.'
-                             % (valid_limit_areas, limit_area))
+            raise ValueError('Invalid limit_area: expecting one of {}, got '
+                             '{}.'.format(valid_limit_areas, limit_area))
 
     # default limit is unlimited GH #16282
     if limit is None: