DOC: update the docstring of  pandas.Series.clip
State: closed

Continuation of https://github.com/pandas-dev/pandas/pull/20178

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>`
- [ ] 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


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

Comments:
Docstrings validator shows some errors related to *args and **kwargs and the dot '.' that can not be avoided.
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.