False positive missing-param-doc when escaping underscore in docstring

[kasium]

Bug description

In this code I need to escape the underscore, because else it's not valid RST.

def get_value(something: int, raise_: bool = False) -> bool:
    """Return the maximum length of a column.

    Args:
        something: the something
        raise\\_: the other

    Returns:
        something
    """
    return something and raise_

Configuration

[MAIN]
load-plugins = ["pylint.extensions.docparams"]

Command used

pylint foo.py

Pylint output

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

Expected behavior

Escaped underscore is understood

Pylint version

pylint 2.15.6
astroid 2.12.12
Python 3.7.2 (default, Jun  2 2022, 07:23:31)

[Pierre-Sassoulas]

Thank you for opening the issue. It seems like we need to "normalize" the variable name recovered from the docstring. It should be doable without too much pylint knowledge.

[clavedeluna]

It seems like to fix this we would either have to:

1. Update this regex https://github.com/PyCQA/pylint/blob/main/pylint/extensions/_check_docs_utils.py#L472 which seems daunting honestly!
2. Do something a bit hacky here before the regex is used, such as entry.replace("\\", "")

@Pierre-Sassoulas thoughts on what would be accepted?

[Pierre-Sassoulas]

I was thinking of "normalizing" the string with a hack initially. If it's detected via regex and it requires a regex change then it might (😄) not be such a good first issue after all...

[clavedeluna]

I'll PR the hacky normalization and see what a variety of maintainers have to say. If it's rejected then we can close it and remove the "good first issue" label 😄

[kasium]

Thanks a lot!