Repository: pandas-dev/pandas

Issue:
Multiindex.fillna() throws NotImplementedError but docs indicate it should work 
#### Code Sample, a copy-pastable example if possible

```python
idx = pd.MultiIndex.from_arrays([['a','b'],[1,np.nan]])
idx.fillna()
idx.values

```
#### Problem description
Error trace:
```
---------------------------------------------------------------------------
NotImplementedError                       Traceback (most recent call last)
<ipython-input-63-feda4f0ee830> in <module>()
      1 idx = pd.MultiIndex.from_arrays([['a','b'],[1,np.nan]])
----> 2 idx.fillna()

~\Anaconda2\envs\python3\lib\site-packages\pandas\core\indexes\multi.py in fillna(self, value, downcast)
    784     def fillna(self, value=None, downcast=None):
    785         # isnull is not implemented for MultiIndex
--> 786         raise NotImplementedError('isnull is not defined for MultiIndex')
    787 
    788     @Appender(_index_shared_docs['dropna'])

NotImplementedError: isnull is not defined for MultiIndex
```

docs seem to state it should work: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.MultiIndex.fillna.html

I am running v20.3 (anaconda doesnt seem to have 21.0 yet). But i've checked code and docs from both v21.0 and master and it seems to be the same

#### Expected Output

`array([('a', 1.0), ('b', 999)], dtype=object)
`
#### Output of ``pd.show_versions()``

<details>

INSTALLED VERSIONS
------------------
commit: None
python: 3.6.3.final.0
python-bits: 64
OS: Windows
OS-release: 10
machine: AMD64
processor: Intel64 Family 6 Model 78 Stepping 3, GenuineIntel
byteorder: little
LC_ALL: None
LANG: None
LOCALE: None.None

pandas: 0.20.3
pytest: 3.2.1
pip: 9.0.1
setuptools: 36.5.0.post20170921
Cython: 0.26.1
numpy: 1.13.3
scipy: 0.19.1
xarray: 0.9.6
IPython: 6.1.0
sphinx: 1.6.3
patsy: 0.4.1
dateutil: 2.6.1
pytz: 2017.2
blosc: None
bottleneck: 1.2.1
tables: 3.4.2
numexpr: 2.6.2
feather: None
matplotlib: 2.1.0
openpyxl: 2.4.8
xlrd: 1.1.0
xlwt: 1.3.0
xlsxwriter: 1.0.2
lxml: 4.1.0
bs4: 4.6.0
html5lib: 0.999999999
sqlalchemy: 1.1.13
pymysql: None
psycopg2: None
jinja2: 2.9.6
s3fs: None
pandas_gbq: None
pandas_datareader: None

</details>



Discussion:
very odd that the doc is showing up at all. Its simply not defined (though it is in a super-class), so maybe bleeding thru somehow.

cc @TomAugspurger 
It is defined, but it just raises `NotImplementedError`. The docstring is inherited though.

We could override the docstring saying it's not implemented, but that's just a short term fix. I'm going to spend some time on our docs over the next couple weeks, so I hope to fix it properly then.
Yes, this is completely expected. 

@robbuckley a short term fix of updating the MultiIndex.fillna docstring is still welcome if you want to do a PR!
@jorisvandenbossche plz see https://github.com/pandas-dev/pandas/pull/18209

Resolving patch:
diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
--- a/pandas/core/indexes/multi.py
+++ b/pandas/core/indexes/multi.py
@@ -809,9 +809,10 @@ def duplicated(self, keep='first'):
 
         return duplicated_int64(ids, keep)
 
-    @Appender(ibase._index_shared_docs['fillna'])
     def fillna(self, value=None, downcast=None):
-        # isna is not implemented for MultiIndex
+        """
+        fillna is not implemented for MultiIndex
+        """
         raise NotImplementedError('isna is not defined for MultiIndex')
 
     @Appender(_index_shared_docs['dropna'])


Test patch: