Escaped '*' in docstring leads to missing-param-doc

[kasium]

Bug description

If a docstring contains the arguments for *args and **kwargs and RST is used, * must be escaped.

def myfunc(value: int, *args: Any) -> None:
    """This is myfunc.

    Args:
        \\*args: this is args
        value: this is value
    """
    print(*args, value)

However, the pylint docparams check doesn't like the escape

Configuration

No response

Command used

pylint --load-plugins pylint.extensions.docparams foo.py --enable all

Pylint output

************* Module foo
foo.py:4:0: W9015: "*args" missing in parameter documentation (missing-param-doc)

Expected behavior

Pylint should ignore escaping

Pylint version

pylint 2.12.2
astroid 2.9.3
Python 3.7.1 (default, Oct 22 2018, 13:16:18) [GCC]

OS / Environment

Linux

Additional dependencies

No response

[kasium]

My suggesting: Before comparing the arguments, "clean" them somehow (e.g. remove escaping)

[DanielNoord]

We currently handle \*args and *args after discussion in #5406.
Change was introduced in https://github.com/PyCQA/pylint/pull/5464/files.

Should be fairly trivial to fix this. However, I wonder why this is needed. Do you need to escape the backslash twice? And are there instances where you need to escape it three or four times? Should we just allow an unlimited amount of backslash in front of the *?

[kasium]

@DanielNoord If I use a single backslash I need to use "r-strings", else I get:

foo.py:8:8: W1401: Anomalous backslash in string: '\*'. String constant might be missing an r prefix. (anomalous-backslash-in-string)

Therefore you need to use \\ to avoid this error. I don't think that more than two backslashes are needed

[DanielNoord]

Is using r-string a problem in your case? This comment seems to indicate that that is the "correct" way to solve this:
#5406 (comment)

[kasium]

@DanielNoord I see your point. However, adding r-strings can lead to some issues in corner cases. I don't remember a concrete example but I guess I found one in the past. So, would you be open to accept a PR or do you think everybody should go with r-strings

[DanielNoord]

Hm, I'm not sure actually. I don't think it hurts to allow \\ but on the other hand: this is the exact case that r-strings are intended for. I can imagine some people might actually be interested in a consider-using-r-string checker in the CodeStyle checker.
If we can't find an actual breaking corner case I think disallowing this and thereby nudging users to the (arguably) intended way to do this could be a nice side-effect. So I'm -0.1 on this. I don't really oppose it, but personally think this is a nice side-effect (as long as nothing breaks of course).

[Pierre-Sassoulas]

I agree with @DanielNoord here.

r-strings can lead to some issues in corner cases

I think we need to know what issues it's causing in what corner case to be able to make a decision. Personally I don't know of any :) Let's keep the discussion open, but as it's hard to prove a negative I'll put this in the 2.14 milestone so we actually close or fix at some point.

[kasium]

Thanks a lot. So I just added used your fix but it doesn't work. Please note, that I use Google-style. Does the fix only consider sphinx-style docstrings?

[DanielNoord]

Hmm, I would need to investigate this. That could actually be the case.