DOC: Deprecation directive in Docstrings should be placed before the extended summary
State: closed

- [x] closes #24143
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

Two methods still show errors due to their docstrings being generated by the [deprecate](https://github.com/pandas-dev/pandas/blob/v0.23.4/pandas/util/_decorators.py#L10) method in _decorators.py. I am not sure if that is to be changed.

Labels:
name: Docs

Comments:
Hello @aqurilla! Thanks for submitting the PR.

 - There are no PEP8 issues in the file [`pandas/core/generic.py`](https://github.com/aqurilla/pandas/blob/3950b3c9f76ed18b225ff90e4444f38c95b8c539/pandas/core/generic.py) !

 - There are no PEP8 issues in the file [`pandas/core/indexes/base.py`](https://github.com/aqurilla/pandas/blob/3950b3c9f76ed18b225ff90e4444f38c95b8c539/pandas/core/indexes/base.py) !

 - There are no PEP8 issues in the file [`pandas/core/indexes/multi.py`](https://github.com/aqurilla/pandas/blob/3950b3c9f76ed18b225ff90e4444f38c95b8c539/pandas/core/indexes/multi.py) !

 - There are no PEP8 issues in the file [`pandas/core/series.py`](https://github.com/aqurilla/pandas/blob/3950b3c9f76ed18b225ff90e4444f38c95b8c539/pandas/core/series.py) !

 - There are no PEP8 issues in the file [`pandas/io/stata.py`](https://github.com/aqurilla/pandas/blob/3950b3c9f76ed18b225ff90e4444f38c95b8c539/pandas/io/stata.py) !

 - There are no PEP8 issues in the file [`scripts/tests/test_validate_docstrings.py`](https://github.com/aqurilla/pandas/blob/3950b3c9f76ed18b225ff90e4444f38c95b8c539/scripts/tests/test_validate_docstrings.py) !

 - There are no PEP8 issues in the file [`scripts/validate_docstrings.py`](https://github.com/aqurilla/pandas/blob/3950b3c9f76ed18b225ff90e4444f38c95b8c539/scripts/validate_docstrings.py) !


# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=h1) Report
> Merging [#24188](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/040f06f731a09fc6e0663cada6697f6602b36f1d?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/24188/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #24188   +/-   ##
=======================================
  Coverage   92.22%   92.22%           
=======================================
  Files         162      162           
  Lines       51828    51828           
=======================================
  Hits        47798    47798           
  Misses       4030     4030
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.62% <ø> (ø)` | :arrow_up: |
| #single | `43% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.58% <ø> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.65% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.27% <ø> (ø)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.7% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=footer). Last update [040f06f...5599343](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=h1) Report
> Merging [#24188](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/77278ba8158457f142e6bba19e6d53a66a3f1322?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/24188/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #24188   +/-   ##
=======================================
  Coverage   92.21%   92.21%           
=======================================
  Files         162      162           
  Lines       51723    51723           
=======================================
  Hits        47695    47695           
  Misses       4028     4028
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.61% <ø> (ø)` | :arrow_up: |
| #single | `43.03% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.58% <ø> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.65% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.27% <ø> (ø)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/24188/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.7% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=footer). Last update [77278ba...3950b3c](https://codecov.io/gh/pandas-dev/pandas/pull/24188?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

> * [x]  closes #24143
> * [ ]  tests added / passed
> * [ ]  passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
> * [ ]  whatsnew entry
> 
> Two methods still show errors due to their docstrings being generated by the [deprecate](https://github.com/pandas-dev/pandas/blob/v0.23.4/pandas/util/_decorators.py#L10) method in _decorators.py. I am not sure if that is to be changed.

The failing check is due to these two methods mentioned above - `pandas.Series.argmax` and `pandas.Series.argmin` whose docstrings are generated by `_decorators.py`. What would be the best way to resolve these?
@jreback can `Series.argmin` and `Series.argmax`, deprecated in `0.21.0` be removed for `0.24.0`? Or arent' we removing deprecated stuff until `1.0`?
@aqurilla I created #24215 which will fix the errors caused by `argmin` and `argmax`. Once it's merged, if you merge master into your branch, it should pass the CI.
Ok, thanks!
Also, @aqurilla if you can merge master into your branch, the PR that fixed `argmin` and `argmax` has been merged, and the CI should be green now.
Thanks for the fixes @aqurilla 

@WillAyd, feel free to open a PR to merge the deprecate methods you mentioned. I think that'll make easier to understand what you meant, than discussing in comments.