DOC: improve fillna() doc for limit keyword (fixes #10002)

Author: mortada

pandas/core/categorical.py

@@ -1180,7 +1180,13 @@ def fillna(self, fill_value=None, method=None, limit=None):
         value : scalar
             Value to use to fill holes (e.g. 0)
         limit : int, default None
-            Maximum size gap to forward or backward fill (not implemented yet!)
+            (Not implemented yet for Categorical!)
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled.
 
         Returns
         -------

pandas/core/generic.py

@@ -2319,7 +2319,12 @@ def fillna(self, value=None, method=None, axis=None, inplace=False,
             other views on this object, (e.g. a no-copy slice for a column in a
             DataFrame).
         limit : int, default None
-            Maximum size gap to forward or backward fill
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled.
         downcast : dict, default is None
             a dict of item->dtype of what to downcast if possible,
             or the string 'infer' which will try to downcast to an appropriate

pandas/core/internals.py

@@ -296,7 +296,7 @@ def fillna(self, value, limit=None, inplace=False, downcast=None):
             if self.ndim > 2:
                 raise NotImplementedError("number of dimensions for 'fillna' "
                                           "is currently limited to 2")
-            mask[mask.cumsum(self.ndim-1)>limit]=False
+            mask[mask.cumsum(self.ndim-1) > limit] = False
 
         value = self._try_fill(value)
         blocks = self.putmask(mask, value, inplace=inplace)