DOC: improve the shared docstring of Series.str.strip()
State: closed

- [ ] closes #xxxx
- [ ] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

Docstring written with @jalammar as part of the pandas sprint at PyData London 2018, guided by @datapythonista. Wasn't too sure of the "Return" definition, so we defaulted to the one written for str_strip. Docstring is shared by the strip, lstrip, and rstrip methods, and validate_docstrings.py script output for the "script" variant is included below: 

################################################################################
##################### Docstring (pandas.Series.str.strip)  #####################
################################################################################

Strip combinations of characters from the left and right sides of strings.

Operates on each element in the given String/Index, and is equivalent to
:meth:`str.strip`.

Parameters
----------
to_strip : str or unicode, optional
    String or unicode specifying the set of characters to be removed from
    the left and right sides. If omitted or None, the strip method defaults to removing
    whitespace and newlines.

Returns
-------
stripped : Series/Index of objects

See Also
--------
Series.str.strip : Removes defined characters from both sides
Series.str.lstrip : Removes defined characters from the left side
Series.str.rstrip : Removes defined characters from the right side

Examples
--------
>>> s = pd.Series(data=['   spacious   ', '__-left_foo',
...                     '-__center_foo__-', 'right_foo-__'])
>>> s.str.strip()[0]
'spacious'

Rather than string matching, all combinations of the `to_strip` parameter's
characters are removed.

>>> s.str.lstrip("-_")[1:]
1         left_foo
2    center_foo__-
3     right_foo-__
dtype: object

>>> s.str.rstrip("-_")[1:]
1      __-left_foo
2    -__center_foo
3        right_foo
dtype: object

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.str.strip" correct. :)







Labels:

Comments:
Really good work. Seems like we didn't coordinate well during the sprint, and it was duplicate work with @Cheukting who submitted #20863.

There is some great work in this PR that should be included in the final result. Can you please decide the PR we want to move forward with, and close the other.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20897?src=pr&el=h1) Report
> Merging [#20897](https://codecov.io/gh/pandas-dev/pandas/pull/20897?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/28edd06498987972953b5c8e1c98b7f55d24b8d2?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/20897/graphs/tree.svg?token=eZ4WkYLtcO&width=650&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/20897?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #20897   +/-   ##
=======================================
  Coverage   91.78%   91.78%           
=======================================
  Files         153      153           
  Lines       49341    49341           
=======================================
  Hits        45287    45287           
  Misses       4054     4054
```

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

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

------

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