Fix PR02 in docstrings

[WuraolaOyewusi]

@datapythonista . I'll like to attempt some of these in pandas

For the *args, **kwargs Unknown parameters. I guess it's because they are on the same line or that : is written after **kwargs

I noticed many of the error docstrings errors such as pandas.Series.str.slice_replace: Unknown parameters {stop, repl, start} flags the parameters as Unknown parameters.

def str_slice_replace(arr, start=None, stop=None, repl=None):
"""
Replace a positional slice of a string with another value.
Parameters
----------
start : int, optional
Left index position to use for the slice. If not specified (None),
the slice is unbounded on the left, i.e. slice from the start
of the string.
stop : int, optional
Right index position to use for the slice. If not specified (None),
the slice is unbounded on the right, i.e. slice until the
end of the string.
repl : str, optional
String for replacement. If not specified (None), the sliced region
is replaced with an empty string.

I'm wondering if something changed in the writing convention of pandas docstrings.

I read the pandas docstring guide. I haven't found the answer there.

Please can you prompt on what I should look out for?

[datapythonista]

Regarding the *args, **kwargs we're happy with that, but we should update the script to not raise an error for it. Not sure if there is an issue in pandas for it already, but feel free to create it if it doesn't, or send a PR.

Not sure about the problem in the docstring of str.slice_replace you copied, looks correct to me. It should be easy to debug the validate_docstrings.py script to get more information about the problem. Let me know if you need help with it.

[WuraolaOyewusi]

Could it be because *args and **kwargs are on the same line in the docstring?

…

On Thu, 29 Aug 2019, 1:35 PM Marc Garcia, ***@***.***> wrote: Regarding the *args, **kwargs we're happy with that, but we should update the script to not raise an error for it. Not sure if there is an issue in pandas for it already, but feel free to create it if it doesn't, or send a PR. Not sure about the problem in the docstring of str.slice_replace you copied, looks correct to me. It should be easy to debug the validate_docstrings.py script to get more information about the problem. Let me know if you need help with it. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#162?email_source=notifications&email_token=AKDK7XEFLVQNP4QHQQDDYB3QG67CPA5CNFSM4ISBLWKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD5OKHVY#issuecomment-526164951>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AKDK7XFPUP6KFKW5B37AHX3QG67CPANCNFSM4ISBLWKA> .

[datapythonista]

I think that's the problem, yes. What I meant is that this is correct, what is not correct is the script for reporting them. You'll have to change the script to "fix" those cases.

[WuraolaOyewusi]

Ok Marc. I will check it out

[WuraolaOyewusi]

Hi @datapythonista . How is EuroSciPy going?

I was checking the validate_docstring.py.

.

From line '462' . I'm wondering could the docstring error be because the parameters were set to 'None'?. Why do they seem to be extra? when the parameters in the function are the same as in the docstring?

[datapythonista]

I think running on an example and printing the value of those variables will be clearer than my explanations. But this is what is going on with an example.

def foo(param1, param2):
    """
    Parameters
    ----------
    param1 : str
    param2 : str
    param3 : str

• doc_params: param1, param2, param3
• signature_params: param1, param2
• extra: param3

The problem for the args, kwargs example is that you will have something like:

• doc_params:
  • param1
  • *args, **kwargs
• signature_params:
  • param1
  • *args
  • **kwargs
• missing:
  • *args
  • **kwargs
• extra:
  • *args, **kwargs

So, the problem is that args and kwargs are considered a single paramter, not two. The solution could be to detect if a paramter named *args, **kwargs exists in the docs, and if it does, convert it to two different parameters in doc_params

[WuraolaOyewusi]

@datapythonista . Ok, I will attempt this