DOC: add checks on the returns section in the docstrings (#23138)
State: closed

- [X] Closes #23138

Updated returns checks in `validate_docstrings.py`:
- check that no name is given when only one value is returned
- check capitalization and punctuation in descriptions

Updated `test_validate_docstrings.py`:
- added some tests to validate these new checks

Labels:
name: Docs
name: CI
description: Continuous Integration

Comments:
Hello @igorfassen! Thanks for updating the PR.

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

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



##### Comment last updated on November 06, 2018 at 10:07 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23432?src=pr&el=h1) Report
> Merging [#23432](https://codecov.io/gh/pandas-dev/pandas/pull/23432?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/c4ac0d68b2418e261f2fd8f3a9f8eca0d5e20474?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #23432      +/-   ##
==========================================
- Coverage   92.31%    92.3%   -0.01%     
==========================================
  Files         166      166              
  Lines       52391    52391              
==========================================
- Hits        48363    48362       -1     
- Misses       4028     4029       +1
```

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

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/23432?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/23432/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `87.68% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23432?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/23432?src=pr&el=footer). Last update [c4ac0d6...5ea7881](https://codecov.io/gh/pandas-dev/pandas/pull/23432?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@igorfassen you will have to merge conflicts with the changes in #23514, in which we codified the error messages. Let me know if you need help.
Actually, that was the first behavior that was implemented, but I eventually simplified this part (see this part of the discussion: https://github.com/pandas-dev/pandas/pull/23432#pullrequestreview-171383495).
Sorry, I didn't see that before. I think @WillAyd comment was more about the implementation, that was somehow tricky.

I think after the refactoring, it should be a bit easier to have a simpler implementation. You can have separate error messages for the case when there is just one output, and for when there are more. It's a bit more repetitive, but I think the implementation should be very straightforward, same as `See Also`.

Sorry about asking too many changes. Does it sound good?
@igorfassen can you make that last change to the name of the `name` variable, and the error messages?
@igorfassen do you have time to make the last changes, and merge master on this, so we can merge?
@datapythonista can you update
lgtm. ping on green.
all green @jreback 
thanks @igorfassen and @datapythonista