DOC: fix PR02 errors in docstrings - pandas.describe_option, pandas.get_option, pandas.reset_option
State: closed

Test results:
Describe_option
```
$ scripts/validate_docstrings.py --format=actions --errors=PR02 pandas.describe_option
...
################################################################################
################################## Validation ##################################
################################################################################

1 Errors found for `pandas.describe_option`:
        SA01    See Also section not found
```
Get_option
```
$ scripts/validate_docstrings.py --format=actions --errors=PR02 pandas.get_option
...
################################################################################
################################## Validation ##################################
################################################################################

2 Errors found for `pandas.get_option`:
        PR01    Parameters {'silent'} not documented
        SA01    See Also section not found
```
Reset_option
```
$ scripts/validate_docstrings.py --format=actions --errors=PR02 pandas.reset_option
...
################################################################################
################################## Validation ##################################
################################################################################

2 Errors found for `pandas.reset_option`:
        PR01    Parameters {'silent'} not documented
        SA01    See Also section not found
```

- [X] Cross-ref: https://github.com/pandas-dev/pandas/issues/57111
- [ ] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [ ] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [ ] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) to new arguments/methods/functions.
- [ ] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.


Labels:
name: Docs
name: Clean

Comments:
Note, `set_option` is a bit trickier because it accepts any number of pairs of arguments, will investigate more there
Thanks for the contribution @jrmylow. I don't understand your changes here. If you're fixing PR02 errors in docstrings, shouldn't we be adding missing parameters to the docs here? I don't know what is the change in the config module, is this intentional?
Oh right, I forgot to document the reason for the changes.

From [1], I understand that the PR01/02 errors are for function parameters that haven't been documented, and documented parameters that aren't in a function respectively.

What I found is that the way these methods are constructed means that they have a strange signature, and the use of inspect/signature is meant to rectify that.

Taking `pandas.reset_option` as an example, the message I get is 3 errors found:
```
PR01  Parameters {'*args', '**kwargs'} not documented
PR02  Unknown parameters {'pat'}
SA01 See Also section not found
```

`reset_option` is not defined directly, instead through a `CallableDynamicDoc`
https://github.com/pandas-dev/pandas/blob/46163c5b66c8bceca1a1cdb76f90bb5c0ee07633/pandas/_config/config.py#L451

The function `_reset_option` is defined and its signature includes the parameter `pat`:
https://github.com/pandas-dev/pandas/blob/46163c5b66c8bceca1a1cdb76f90bb5c0ee07633/pandas/_config/config.py#L199

The docstring `_reset_option_tmpl` is also defined and references the parameter `pat` as `str/regex`:
https://github.com/pandas-dev/pandas/blob/46163c5b66c8bceca1a1cdb76f90bb5c0ee07633/pandas/_config/config.py#L411
https://github.com/pandas-dev/pandas/blob/46163c5b66c8bceca1a1cdb76f90bb5c0ee07633/pandas/_config/config.py#L424

However, the PR02 error does not recognise that `pat` exists despite being in both the `_reset_option` signature and the docstring.

When examining the signature of `pandas.reset_option` using `inspect.signature()` I find that it is actually:
```
>>> inspect signature(pandas.reset_option)
<Signature (*args, **kwds) -> 'T'>
```

The fix applied has been to copy the function signature (in this case `_reset_option` and apply it to `CallableDynamicDoc`)

@datapythonista hope this makes sense, happy to proceed with another method if there is a strong argument against this way

[1]: https://numpydoc.readthedocs.io/en/latest/validation.html
Note as a follow-on from the above, the reason this does not fix `set_options` is that this function actually does accept any number of args and kwargs (contradicting the documentation, which only specifies `set_option(pat, value)`), and I haven't figured out a clean way to fix this yet.
This fix only fixes 3 out of 4 of the options. `set_option` is tricky because the underlying method signature is in fact `_set_option(*args, **kwargs)` and contradicts the docstring, which expects `set_option(pat, value)`. I wanted to fix all of them in a single PR given it's the same issue and the same module.
I would personally prefer if you address further fixes in new PRs. For reviewers, we'll have to keep reviewing the changes you already have at every iteration if you continue working on this PR, which is not a big problem since the changes are small, but it's still more efficient if we have to review only new changes in the future.
Ok fair, I'll un-draft it and wait for the code checks to all pass
Thanks @jrmylow