DOC: update the pandas.DataFrame.clip docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwargs', 'args'} not documented
		Unknown parameters {'*args, **kwargs'}
		Parameter "*args, **kwargs" has no type
(pandas_dev) Demetris-Retina-MacBook-Pro:pandas demetri$ git diff upstream/master -u -- "*.py" | flake8 --diff
(pandas_dev) Demetris-Retina-MacBook-Pro:pandas demetri$ python scripts/validate_docstrings.py pandas.DataFrame.clip

################################################################################
###################### Docstring (pandas.DataFrame.clip)  ######################
################################################################################

Trim values at input threshold(s).

Elements above/below the upper/lower thresholds will be changed to
upper/lower thresholds. Clipping data is a method for dealing with
out-of-range elements. If some elements are too large or too small,
clipping is one way to transform the data into a reasonable range.

Parameters
----------
lower : float, array-like or None, default None
    Lower threshold for clipping.  Values smaller than `lower` will be
    converted to `lower`.
upper : float, array-like or None, default None
    Upper threshold for clipping.  Values larger than `upper` will be
    converted to `upper`.
axis : {0 or 'index', 1 or 'columns', None}, default None
    Apply clip by index (i.e. by rows) or columns.
inplace : boolean, default False
    Whether to perform the operation in place on the data
        .. versionadded:: 0.21.0.
*args, **kwargs
    Additional keywords have no effect but might be accepted
    for compatibility with numpy.

Returns
-------
`Series` or `DataFrame`.
    Original input with those values above/below the
    `upper`/`lower` thresholds set to the threshold values.

References
-----
.. [1] Tukey, John W. "The future of data analysis." The annals of
    mathematical statistics 33.1 (1962): 1-67.

See Also
--------
DataFrame.clip : Trim values at input threshold(s).
Series.clip : Trim values at input threshold(s).
Series.clip_lower : Return copy of the input with values below given
    value(s) truncated.
Series.clip_upper : Return copy of input with values above given
    value(s) truncated.
DataFrame.clip_lower : Return copy of the input with values below given
    value(s) truncated.
DataFrame.clip_upper : Return copy of input with values above given
    value(s) truncated.
DataFrame.quantile : Return values at the given quantile over requested
    axis, a la numpy.percentile.

Examples
--------
>>> df = pd.DataFrame({'a': [-1, -2, -100],
...                    'b': [1, 2, 100]},
...                    index=['foo', 'bar', 'foobar'])
>>> df
     a  b
foo -1  1
bar -2  2
foobar  -100    100

>>> df.clip(lower=-10, upper=10)
     a  b
foo -1  1
bar -2  2
foobar  -10 10

You can clip each column or row with different thresholds by passing
a ``Series`` to the lower/upper argument. Use the axis argument to clip
by column or rows.

>>> col_thresh = pd.Series({'a': -5, 'b': 5})
>>> df.clip(lower=col_thresh, axis='columns')
     a  b
foo -1  5
bar -2  5
foobar  -5  100

Clip the foo, bar, and foobar rows with lower thresholds 5, 7, and 10.

>>> row_thresh = pd.Series({'foo': 0, 'bar': 1, 'foobar': 10})
>>> df.clip(lower=row_thresh, axis='index')
    a   b
foo 0   1
bar 1   2
foobar  10  100

Winsorizing [1]_ is a related method, whereby the data are clipped at
the 5th and 95th percentiles. The ``DataFrame.quantile`` method returns
a ``Series`` with column names as index and the quantiles as values.
Use ``axis='columns'`` to apply clipping to columns.

>>> lower, upper = df.quantile(0.05), df.quantile(0.95)
>>> df.clip(lower=lower, upper=upper, axis='columns')
     a  b
foo -1.1    1.1
bar -2.0    2.0
foobar  -90.2   90.2

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwargs', 'args'} not documented
		Unknown parameters {'*args, **kwargs'}
		Parameter "*args, **kwargs" has no type
```



Changes:

* `*args` and `**kwargs` description taken from #20256 in the name of consistency

Labels:
name: Docs
name: Numeric Operations
description: Arithmetic, Comparison, and Logical operations

Comments:
@cmdelatorre `validate_clip_with_axis` is going over my head.  I'm not sure what `validate_clip_with_axis` does.  Open to suggestions on what to add to docstring, or would appreciate reading suggestions.
Hello @Dpananos! Thanks for updating the PR.



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

##### Comment last updated on March 13, 2018 at 15:29 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20212?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@5b0caf4`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff            @@
##             master   #20212   +/-   ##
=========================================
  Coverage          ?   91.73%           
=========================================
  Files             ?      150           
  Lines             ?    49168           
  Branches          ?        0           
=========================================
  Hits              ?    45102           
  Misses            ?     4066           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <100%> (?)` | |
| #single | `41.86% <50%> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20212?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20212/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.84% <100%> (ø)` | |

------

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

@Dpananos I merged the other PR that also edited the same docstring (https://github.com/pandas-dev/pandas/pull/20256). This will cause conflicts for this one, so you will need to resolve them (sorry for that trouble, but wanted to acknowledge both PRs, and yours adds some extra than the other).

If you need any help with updating the PR (merge upstream/master), let me know! 
@jorisvandenbossche  I'm not really certain what happened.  So you merged another docstring and now I have a conflict?  How should I go about updating the PR?
So to update the PR with the latest changes on master, you can do:

```
git checkout docstring_clip
git fetch upstream
git merge upstream/master
```

This will give conflicts in the `generic.py` file. 

Solving these conflicts will mean merging somehow the two docstring (you can just use your judgement on which of the two versions you find best for each element of the docstring, certainly your examples were more elaborate I think). 
Once you solved the conflicts, you need to do:

```
git add pandas/core/generic.py
git commit
```

and push again to the branch on origin.

I would say: try it out, and if you have troubles with, I can also do it.