DOC: Clarify DataFrame.where tries to maintain dtype of DataFrame when providing fill_value

[mroeschke]

In [1]: In [1]: psr = pd.Series(range(10), dtype="int16")

In [2]: In [4]: fill_value = 100.0

In [3]: In [5]: expect = psr.where(psr > 0, fill_value)

1.4.3
In [4]: expect
Out[4]:
0    100.0
1      1.0
2      2.0
3      3.0
4      4.0
5      5.0
6      6.0
7      7.0
8      8.0
9      9.0
dtype: float64

1.5
In [6]: expect
Out[6]:
0    100
1      1
2      2
3      3
4      4
5      5
6      6
7      7
8      8
9      9
dtype: int16

Bisected to

Author: @jbrockmendel
Date: Sun Jan 30 15:45:55 2022 -0800

REF: avoid upcast/downcast in Block.where (#45582)

Seems like an intentional change, but it's not really clear from the where docs whether fill_value dtype or DataFrame dtype takes priority.

[jbrockmendel]

intentional change bc the 100.0 can be cast to int16 losslessly

[mroeschke]

Okay changing to a documentation issue then.