DOC/CLN: Fix errors in Series docstrings
State: closed

Fixes (or starts to fix) a few errors in `Series` docstrings.  On a related note, it seems `validate_docstrings.py` yields this error for a large number of docstrings:

```
The first line of the Returns section should contain only the type, unless multiple values are being returned
```

which seems to happen whenever the return value is named.  Should these be errors?

Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24945?src=pr&el=h1) Report
> Merging [#24945](https://codecov.io/gh/pandas-dev/pandas/pull/24945?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/0c4113fa0906273007cc12a4bcadff85d943dc84?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/24945/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24945?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #24945   +/-   ##
=======================================
  Coverage   92.37%   92.37%           
=======================================
  Files         166      166           
  Lines       52388    52388           
=======================================
  Hits        48396    48396           
  Misses       3992     3992
```

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

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24945?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.68% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24945?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/24945?src=pr&el=footer). Last update [0c4113f...6791923](https://codecov.io/gh/pandas-dev/pandas/pull/24945?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/24945?src=pr&el=h1) Report
> Merging [#24945](https://codecov.io/gh/pandas-dev/pandas/pull/24945?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/2e38d5552a5c7b2c0091cecddd483f4f08ad1d2c?src=pr&el=desc) will **decrease** coverage by `0.02%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #24945      +/-   ##
==========================================
- Coverage   92.37%   92.35%   -0.03%     
==========================================
  Files         166      166              
  Lines       52408    52314      -94     
==========================================
- Hits        48412    48312     -100     
- Misses       3996     4002       +6
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.78% <ø> (-0.01%)` | :arrow_down: |
| #single | `42.84% <ø> (-0.03%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24945?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.69% <ø> (ø)` | :arrow_up: |
| [pandas/core/groupby/ops.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9vcHMucHk=) | `94.15% <0%> (-2.58%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.39% <0%> (-0.24%)` | :arrow_down: |
| [pandas/core/groupby/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9nZW5lcmljLnB5) | `86.98% <0%> (-0.18%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `96.65% <0%> (-0.16%)` | :arrow_down: |
| [pandas/core/internals/managers.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW50ZXJuYWxzL21hbmFnZXJzLnB5) | `95.95% <0%> (-0.11%)` | :arrow_down: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `88.05% <0%> (-0.09%)` | :arrow_down: |
| [pandas/core/internals/blocks.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW50ZXJuYWxzL2Jsb2Nrcy5weQ==) | `94.1% <0%> (-0.07%)` | :arrow_down: |
| [pandas/core/resample.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzYW1wbGUucHk=) | `97.22% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/panel.py](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcGFuZWwucHk=) | `97.9% <0%> (-0.01%)` | :arrow_down: |
| ... and [16 more](https://codecov.io/gh/pandas-dev/pandas/pull/24945/diff?src=pr&el=tree-more) | |

------

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

Hello @dsaxton! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on February 07, 2019 at 01:56 Hours UTC
> which seems to happen whenever the return value is named. Should these be errors?

Yea this is intentional. Unless multiple values are being returned should just have a type in the Returns section
This should be the output for the docstrings edited so far in this PR.

`to_string`

```
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.to_string" correct. :)
```

`to_dict`

```
2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.to_dict" correct. :)
```

`to_frame`

```
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.to_frame" correct. :)
```

`to_sparse`

(I think the first error is wrong here because `"integer"` is actually a string in the docstring.  For this one I'm not familiar enough with the method to add a good description.  Also, I think this will be deprecated soon anyways?)

```
2 Errors found:
	Parameter "kind" type should use "int" instead of "integer"
	Parameter "kind" has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
```

`count`

```
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.count" correct. :)
```

`mode`

```
2 Warnings found:
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.mode" correct. :)
```

`drop_duplicates`

(This is another one where the lowercase letter is an argument option.)

```
1 Errors found:
	Parameter "keep" description should start with a capital letter
1 Warnings found:
	No extended summary found
```

`duplicated`

(Same here.)

```
1 Errors found:
	Parameter "keep" description should start with a capital letter
```

`idxmin`

```
2 Errors found:
	Parameters {*args, **kwargs} not documented
	Unknown parameters {*args, **kwargs}
```

`idxmax`

```
2 Errors found:
	Parameters {*args, **kwargs} not documented
	Unknown parameters {*args, **kwargs}
```

`round`

```
1 Errors found:
	Parameters {**kwargs, *args} not documented
2 Warnings found:
	No extended summary found
	No examples section found
```

`quantile`

```
6 Errors found:
	Parameter "q" description should start with a capital letter
	Parameter "q" description should finish with "."
	Parameter "interpolation" has no description
	Return value description should start with a capital letter
	Missing description for See Also "core.window.Rolling.quantile" reference
	Missing description for See Also "numpy.percentile" reference
```

`corr`

```
6 Errors found:
	Parameter "other" has no description
	Parameter "method" description should start with a capital letter
	Parameter "method" description should finish with "."
	Parameter "min_periods" description should finish with "."
	Return value has no description
	flake8 error: E124 closing bracket does not match visual indentation
2 Warnings found:
	No extended summary found
	See Also section not found
```

`cov`

```
4 Errors found:
	Parameter "other" has no description
	Parameter "min_periods" description should finish with "."
	Return value has no description
	Return value has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
```

`diff`

```
Docstring for "pandas.core.series.Series.diff" correct. :)
```

`append`

```
6 Errors found:
	Parameter "to_append" has no description
	Parameter "ignore_index" type should use "bool" instead of "boolean"
	Parameter "verify_integrity" type should use "bool" instead of "boolean"
	Parameter "verify_integrity" description should finish with "."
	Return value has no description
	flake8 error: E231 missing whitespace after ',' (2 times)
1 Warnings found:
	No extended summary found
```

`sort_index`

```
Docstring for "pandas.core.series.Series.sort_index" correct. :)
```

`argsort`

```
4 Errors found:
	Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
	Summary should fit in a single line
	Parameter "kind" description should finish with "."
	Missing description for See Also "numpy.ndarray.argsort" reference
1 Warnings found:
	No examples section found
```

`swaplevel`

```
4 Errors found:
	Parameters {j, copy, i} not documented
	Unknown parameters {i, j}
	Parameter "i, j" type should use "str" instead of "string"
	Return value has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
```

`unstack`

```
7 Errors found:
	Summary should fit in a single line
	Parameter "level" type should use "str" instead of "string"
	Parameter "level" description should finish with "."
	Parameter "fill_value" description should start with a capital letter
	Parameter "fill_value" description should finish with "."
	Return value has no description
	flake8 error: E128 continuation line under-indented for visual indent
1 Warnings found:
	See Also section not found
```

`rename`

```
7 Errors found:
	Parameters {**kwargs} not documented
	Unknown parameters {level, inplace, copy}
	Parameter "index" description should start with a capital letter
	Parameter "copy" description should finish with "."
	Return value has no description
	Missing description for See Also "Series.rename_axis" reference
	flake8 error: E261 at least two spaces before inline comment
```

`drop`

```
4 Errors found:
	Parameters {columns, index} not documented
	Unknown parameters {index, columns}
	Return value has no description
	flake8 error: E231 missing whitespace after ',' (3 times)
```

`isin`

```
Docstring for "pandas.core.series.Series.isin" correct. :)
```

`between`

```
Docstring for "pandas.core.series.Series.between" correct. :)
```

`from_csv`

```
3 Errors found:
	Parameter "path" has no description
	Return value has no description
	Missing description for See Also "read_csv" reference
1 Warnings found:
	No examples section found
```

`valid`

```
2 Errors found:
	Parameters {inplace, **kwargs} not documented
	No Returns section found
2 Warnings found:
	See Also section not found
	No examples section found
```

`to_period`

```
2 Errors found:
	Summary should fit in a single line
	Parameters {copy} not documented
2 Warnings found:
	See Also section not found
	No examples section found
```
@WillAyd Side question, but when I merge with master on GitHub, how do I prevent lots of unrelated files from being marked as edited in my PR when I pull locally and then later push?
Typically I would do the below locally on branch in question

```sh
git fetch upstream
git merge upstream/master
<FIX CONFLICTS IF ANY, then git merge --continue>
git push origin your-branch-name
```
can you merge master
@dsaxton seeing some movement on this and maybe other PRs. Please ping when you are ready for review
@WillAyd Would be happy to have you take a look whenever you get a chance
Thanks - latest version looks like a good improvement over what was there previously. Can you provide updated script validations? Probably OK to leave a few out there for follow up PRs just want to make sure we haven't increased number of errors before approving
@WillAyd Still some errors / warnings here and there (some of which I don't think are real, others I'm not certain of the fix), but I think we've cleaned up a good chunk of them.

```
to_string

3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.to_string" correct. :)

to_dict

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.to_dict" correct. :)

to_frame

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.to_frame" correct. :)

to_sparse

2 Errors found:
	Parameter "kind" type should use "int" instead of "integer"
	Parameter "kind" has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

count

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.count" correct. :)

mode

2 Warnings found:
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.mode" correct. :)

drop_duplicates

1 Errors found:
	Parameter "keep" description should start with a capital letter
1 Warnings found:
	No extended summary found

duplicated

1 Errors found:
	Parameter "keep" description should start with a capital letter

idxmin

2 Errors found:
	Parameters {**kwargs, *args} not documented
	Unknown parameters {*args, **kwargs}

idxmax

2 Errors found:
	Parameters {**kwargs, *args} not documented
	Unknown parameters {*args, **kwargs}

round

1 Errors found:
	Parameters {*args, **kwargs} not documented
1 Warnings found:
	No extended summary found

quantile

4 Errors found:
	Parameter "q" description should start with a capital letter
	Parameter "interpolation" has no description
	Missing description for See Also "core.window.Rolling.quantile" reference
	Missing description for See Also "numpy.percentile" reference
1 Warnings found:
	No extended summary found

corr

(flake8 is complaining about this code block, which I don't think is necessarily wrong.)

        >>> def histogram_intersection(a, b):
        ...     v = np.minimum(a, b).sum().round(decimals=1)
        ...     return v
        >>> s1 = pd.Series([.2, .0, .6, .2])
        >>> s2 = pd.Series([.3, .6, .0, .1])
        >>> s1.corr(s2, method=histogram_intersection)
        0.3

4 Errors found:
	Parameter "method" description should start with a capital letter
	Parameter "method" description should finish with "."
	flake8 error: E302 expected 2 blank lines, found 0
	flake8 error: E305 expected 2 blank lines after class or function definition, found 0
2 Warnings found:
	No extended summary found
	See Also section not found

cov

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.cov" correct. :)

diff

Docstring for "pandas.core.series.Series.diff" correct. :)

append

1 Warnings found:
	No extended summary found
Docstring for "pandas.core.series.Series.append" correct. :)

sort_index

Docstring for "pandas.core.series.Series.sort_index" correct. :)

argsort

4 Errors found:
	Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
	Summary should fit in a single line
	Parameter "kind" description should finish with "."
	Missing description for See Also "numpy.ndarray.argsort" reference
1 Warnings found:
	No examples section found

swaplevel

2 Errors found:
	Parameters {i, j, copy} not documented
	Unknown parameters {i, j}
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

unstack

1 Errors found:
	Summary should fit in a single line
1 Warnings found:
	See Also section not found

rename

3 Errors found:
	Parameters {**kwargs} not documented
	Unknown parameters {level, copy, inplace}
	Parameter "index" description should start with a capital letter

drop

2 Errors found:
	Parameters {columns, index} not documented
	Unknown parameters {index, columns}

isin

Docstring for "pandas.core.series.Series.isin" correct. :)

between

Docstring for "pandas.core.series.Series.between" correct. :)

from_csv

3 Errors found:
	Parameter "path" has no description
	Return value has no description
	Missing description for See Also "read_csv" reference
1 Warnings found:
	No examples section found

valid

2 Errors found:
	Parameters {**kwargs, inplace} not documented
	No Returns section found
2 Warnings found:
	See Also section not found
	No examples section found

to_period

1 Errors found:
	Summary should fit in a single line
2 Warnings found:
	See Also section not found
	No examples section found
```
Makes sense. I checked most remaining and most are errors with the validator itself (ex: things that start with bullet points in description). I think this is a good enough improvement to move forward so we don't get stuck in a holding pattern forever.

cc @datapythonista - looks like there might be a new error for the below line, where `'integer'` is a valid argument but the validator complains about it not being written out as `int`. I'll open up an issue for that separately
Thanks @dsaxton !