CLN: a batch of replacements of @Appender() with @doc()
State: closed

- [x] xref #31942
- [x] tests added / passed
- [x] passes `black pandas`
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] replaces a number of uses of @Appender() with @doc() in `core/generic.py`


Labels:
name: Clean

Comments:
I keep getting an error from a failed pytest. This happens in CI, see https://dev.azure.com/pandas-dev/pandas/_build/results?buildId=31810&view=logs&j=3a03f79d-0b41-5610-1aa4-b4a014d0bc70&t=4d05ed0e-1ed3-5bff-dd63-1e957f2766a9
and locally
`(pandas-dev) C:\Users\David\source\repos\pandas-smartvinnetou>pytest pandas/tests/frame/methods/test_shift.py::TestDataFrameShift::test_shift_dt64values_int_fill_deprecated
=========================================================================================================================== test session starts ===========================================================================================================================
platform win32 -- Python 3.7.4, pytest-5.3.5, py-1.8.1, pluggy-0.13.1
rootdir: C:\Users\David\source\repos\pandas-smartvinnetou, inifile: setup.cfg
plugins: hypothesis-5.5.3, asyncio-0.10.0, cov-2.8.1, forked-1.1.3, xdist-1.31.0
collected 1 item                                                                                                                                                                                                                                                           

pandas\tests\frame\methods\test_shift.py F                                                                                                                                                                                                                           [100%]

================================================================================================================================ FAILURES =================================================================================================================================
______________________________________________________________________________________________________ TestDataFrameShift.test_shift_dt64values_int_fill_deprecated _______________________________________________________________________________________________________

self = <pandas.tests.frame.methods.test_shift.TestDataFrameShift object at 0x0000020E4201C088>

    def test_shift_dt64values_int_fill_deprecated(self):
        # GH#31971
        ser = pd.Series([pd.Timestamp("2020-01-01"), pd.Timestamp("2020-01-02")])
        df = ser.to_frame()
    
        with tm.assert_produces_warning(FutureWarning):
>           result = df.shift(1, fill_value=0)

pandas\tests\frame\methods\test_shift.py:195:
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

self = <contextlib._GeneratorContextManager object at 0x0000020E42021BC8>, type = None, value = None, traceback = None

    def __exit__(self, type, value, traceback):
        if type is None:
            try:
>               next(self.gen)
E               AssertionError: Warning not set with correct stacklevel. File where warning is raised: C:\Users\David\source\repos\pandas-smartvinnetou\pandas\core\frame.py != C:\Users\David\source\repos\pandas-smartvinnetou\pandas\tests\frame\methods\test_shift.py. W
arning message: Passing <class 'int'> to shift is deprecated and will raise in a future version, pass Timestamp instead.

..\..\..\AppData\Local\Programs\Python\Python37\lib\contextlib.py:119: AssertionError
============================================================================================================================ 1 failed in 0.50s ============================================================================================================================

(pandas-dev) C:\Users\David\source\repos\pandas-smartvinnetou>
`
I changed docstings and the related decorator. I have not changed any code. The error messages are not terribly informative.

Can someone shed some light on this failed test? Is this an issue with raising the wrong warning for some reason?
After more investigation, I believe that the reason of the failed test the change of the depth of the stack introduced by the `doc()` decorator. It adds and extra frame per call to the stack (the `wrapper()` at https://github.com/pandas-dev/pandas/blob/master/pandas/util/_decorators.py#L224). The `Appender()` decorator changed the function it was decorating directly without introducing a wrapper, see https://github.com/pandas-dev/pandas/blob/master/pandas/util/_decorators.py#L381.

As the `doc()` decorator is called twice, there are two more frames on the stack (then there were when `Appender()` was used) when the `FutureWarning()` is raised at https://github.com/pandas-dev/pandas/blob/master/pandas/core/arrays/datetimelike.py#L790.

And then there is a mismatch when the failing test is checking the raised warning at https://github.com/pandas-dev/pandas/blob/master/pandas/_testing.py#L2366. 

I can fix this mismatch by increasing the `stacklevel` at https://github.com/pandas-dev/pandas/blob/master/pandas/core/arrays/datetimelike.py#L795 to 9. This makes the `actual_warning.filename` and `caller.filename` values at https://github.com/pandas-dev/pandas/blob/master/pandas/_testing.py#L2372 point to `pandas\\tests\\frame\\methods\\test_shift.py`.

Can someone who knows the logic behind all this code confirm that this is the right change? @jorisvandenbossche ?

> Can someone who knows the logic behind all this code confirm that this is the right change? 

If the number of wrapping functions increased, then increasing the number specified in `stacklevel` is indeed the correct thing to do.
@smartvinnetou thanks a lot!