Wrong behaviour for missing-param-doc test in Pylint 2.12.2

[domibarton]

Bug description

When I run Pylint 2.12.2 against a file with *args and/or **kwargs function or method parameters, it will fail.

There's currently no way how I can fix the error. I know about the new syntax (i.e. :param list *args: instead of :param list args:), but non of both syntaxes will work! In Pylint 2.12.1 it works, in 2.12.2 it no longer works.

The test file is this:

'''
Test Pylint.
'''

def test(*args):
    '''
    Test Pylint.

    :param list *args: The arguments
    '''
    print(args)

Configuration

https://git.confirm.ch/confirm/development-guidelines/-/blob/master/configs/pylintrc

Command used

pip install pylint==2.12.2
pylint test.py

Pylint output

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

Expected behavior

The missing-param-doc shouldn't occur.

To clarify, this DOESN'T WORK:

pip install pylint==2.12.2
pylint test.py

But THIS WORKS:

pip install pylint==2.12.1
pylint test.py

Pylint version

pylint 2.12.1
astroid 2.9.0
Python 3.9.0 (v3.9.0:9cf6752276, Oct  5 2020, 11:29:23)
[Clang 6.0 (clang-600.0.57)]

OS / Environment

Tested on: Debian 10 & macOS 10.15
Tested with: Python 3.5 3.6, 3.7, 3.8 & 3.9

Additional dependencies

No response

[DanielNoord]

This has been changed with #5464 based on discussion in #5406. Although I think it would be good to allow *args Sphinx doesn't actually allow it and requires a backslash (\*args). We have opted to keep requiring the asterisk (change introduced in 2.12), therefore \*args is the only supported form for Sphinx docstrings now.

Sorry for updating the syntax so soon after the previous change. We did not find a good explanation of the Sphinx requirements before working on 2.12 and made a bad assumption about the required syntax.

For other stumbling upon this issue:
If you update from 2.11.x to 2.12.2 and use Sphinx docstring you will now need to use \*args instead of args or *args.

Hope this helps!

[domibarton]

This has been changed with #5464 based on discussion in #5406. Although I think it would be good to allow *args Sphinx doesn't actually allow it and requires a backslash (\*args). We have opted to keep requiring the asterisk (change introduced in 2.12), therefore \*args is the only supported form for Sphinx docstrings now.

Sorry for updating the syntax so soon after the previous change. We did not find a good explanation of the Sphinx requirements before working on 2.12 and made a bad assumption about the required syntax.

For other stumbling upon this issue: If you update from 2.11.x to 2.12.2 and use Sphinx docstring you will now need to use \*args instead of args or *args.

Hope this helps!

Hi @DanielNoord

Thanks for the explanation, I didn't expect such a fast answer. This makes absolute sense now, so I'll fix my whole code base / docstrings now ;)

Thanks & have a nice weekend!

[DanielNoord]

No worries! Hopefully updating doesn't cost you too much time!

By the way, you might be interested in sphinx-doc/sphinx#9893 which was opened because of the initial discussion in pylint.

[domibarton]

You know Pylint doesn't complain when I use the old-style :param list args in the constructor? Even with 2.12.2? For methods it will fail, for the constructor it will shut up :)

[DanielNoord]

Hmm, that might actually be a false negative! Could you open up a new issue with a minimal code reproducing code example? I could perhaps take a look at it for 2.13 :)

[domibarton]

Hmm, that might actually be a false negative! Could you open up a new issue with a minimal code reproducing code example? I could perhaps take a look at it for 2.13 :)

ok 👍