DOC: update the docstring of pandas.Series.clip

[dcanones]

Continuation of #20178

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

(pandas_dev) david@david-TM1604:~/repos/pandas$ python scripts/validate_docstrings.py pandas.Series.clip ################################################################################ ######################## Docstring (pandas.Series.clip) ######################## ################################################################################ Trim values at input threshold(s). Assigns values outside boundary to boundary values. Thresholds can be singular values or array like, and in the latter case the clipping is performed element-wise in the specified axis. Parameters ---------- lower : float or array_like, default None Minimum threshold value. All values below this threshold will be set to it. upper : float or array_like, default None Maximum threshold value. All values above this threshold will be set to it. axis : int or string axis name, optional Align object with lower and upper along the given axis. 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. See Also -------- Series.clip_lower : Clip values below specified threshold(s). Series.clip_upper : Clip values above specified threshold(s). Returns ------- `pandas.Series` Series with the values outside the clip boundaries replaced Examples -------- >>> data = {'col_0': [9, -3, 0, -1, 5], 'col_1': [-2, -7, 6, 8, -5]} >>> df = pd.DataFrame(data) >>> df col_0 col_1 0 9 -2 1 -3 -7 2 0 6 3 -1 8 4 5 -5 >>> df.clip(-4, 6) col_0 col_1 0 6 -2 1 -3 -4 2 0 6 3 -1 6 4 5 -4 >>> t = pd.Series([2, -4, -1, 6, 3]) >>> t 0 2 1 -4 2 -1 3 6 4 3 dtype: int64 >>> df.clip(t, t + 4, axis=0) col_0 col_1 0 6 2 1 -3 -4 2 0 3 3 6 8 4 5 3 ################################################################################ ################################## Validation ################################## ################################################################################ Errors found:	Errors in parameters section	Parameters {'args', 'kwargs'} not documented	Unknown parameters {'*args, **kwargs'}	Parameter "inplace" description should finish with "."	Parameter "*args, **kwargs" has no type 

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[dcanones]

Docstrings validator shows some errors related to *args and **kwargs and the dot '.' that can not be avoided.

[Dpananos]

Currently working on the pandas.DataFrame.clip #20212 . Interested in knowing how to properly document use for *args and **kwargs. Looks like they are passed into validate_clip_with_axis, but I still don't know why the end user would make use of them.

[jreback]

I don't think we quote here, the original: clipped : Series is fine

[jorisvandenbossche]

Looks good!

Made a small change to make it generic for Series and DataFrame.
Since there is another PR that also edits this docstring (# #20212), will merge this, and we can further refine in the other PR