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

[mortada]

fixes #10002

[jorisvandenbossche]

Maybe put the not implemented yet first? (and maybe also explicitely "for Categorical")

[mortada]

good idea, will update

[jorisvandenbossche]

Actually, in the way I interpret "maximum size gap to forward or backward fill", this is not fully correct.

I interpret it as "only fill that gap if the gap is not larger as 'limit'", but it is "per gap, fill a maximum numbers of 'limit'":

In [10]: s=pd.Series(range(4), index=[1,2,5,9])

In [11]: s = s.reindex(range(10))

In [12]: s
Out[12]:
0   NaN
1     0
2     1
3   NaN
4   NaN
5     2
6   NaN
7   NaN
8   NaN
9     3
dtype: float64

In [13]: s.fillna(method='ffill', limit=2)
Out[13]:
0   NaN
1     0
2     1
3     1
4     1
5     2
6     2
7     2
8   NaN
9     3
dtype: float64

[mortada]

What if we rephrase it to say something like:

"maximum number of consecutive holes to forward or backward fill"

[jreback]

lgtm

[jorisvandenbossche]

It is a bit subjective, but I would personally still interpret that not fully correct (I see a hole as possibly multiple NaN values if they are consecutive, but maybe this is not correct language?).
Otherwise: "maximum number of consecutive NaN values to forward/backward file per hole"

I think an example in the docstring to show this behaviour would possibly be the most clarifying.

[mortada]

Ah yeah I suppose you could interpret a "hole" as multiple NaNs. @jorisvandenbossche please see the updated changes in the diff, I wonder if it's now clear to you.

[jorisvandenbossche]

one small nitpick: maybe "along the entire axis"

For the rest everything clear now! Thanks!

[mortada]

sure definitely more clear now, thanks!

[jorisvandenbossche]

Thanks!