False positive missing-param-doc on numpy style when : <type> omitted

[maread99]

Bug description

"""A module."""


# https://numpydoc.readthedocs.io/en/latest/format.html#parameters
# The numpy style guide describes that parameters can be defined without
# being followed with a semi-colon and the type, i.e. arg2 below should
# not fail either of the raised checks.

def func(arg1: bool, arg2: bool):
    """Return args.

    Parameters
    ----------
    arg1 : bool
        arg1

    arg2
        arg2
    """
    return arg1, arg2

Configuration

[MASTER]
load-plugins=pylint.extensions.docparams

[PARAMETER_DOCUMENTATION]
default-docstring-type=numpy

Command used

pylint pylint_bug.py

Pylint output

************* Module pylint_bug
pylint_bug.py:9:0: W9015: "arg2" missing in parameter documentation (missing-param-doc)
pylint_bug.py:9:0: W9012: Missing return type documentation (missing-return-type-doc)

Expected behavior

Would not have expected either missing-param-doc or missing-return-type-doc checks to have failed.

Pylint version

pylint 2.11.1
astroid 2.8.4
Python 3.8.2 (tags/v3.8.2:7b3ab59, Feb 25 2020, 23:03:10) [MSC v.1916 64 bit (AMD64)]

OS / Environment

VS Code 1.61.2
Windows 10 Pro 21H1

Additional dependencies

No response

[DanielNoord]

With respect to missing-return-type-doc:
I think this is due to the fact that the section Returns is missing.
Perhaps this is allowed in numpy documentation and we should update this, but if you look at the docs you linked there is actually a section on return type annotation.
https://numpydoc.readthedocs.io/en/latest/format.html#returns

So this should work:

def func(arg1: bool, arg2: bool):
    """Return args.

    Parameters
    ----------
    arg1 : bool
        arg1

    arg2
        arg2
     
    Returns
    ----------
    bool
    bool (?, the type is required for return type documentation)
    """
    return arg1, arg2

missing-param-doc seems to be a false positive indeed.

[maread99]

@DanielNoord, absolutely, apologises for confusing the issue. Do you want me to close and raise a new tidier version?

and thank you for the immediate response!

[DanielNoord]

No worries. It is already really helpful to have some code that should reproduce the issue. No need to open a new one.

It is strange as I feel I have visited this part of the code recently and fixed something similar, but I can't find that PR. I will assign myself and investigate in the coming days!

[maread99]

Tremendous, thanks!

Might you have been looking at this issue? It was the only one I could find along simlar lines.

[DanielNoord]

No, but I might as well look at that one at the same time 😄

[maread99]

No, but I might as well look at that one at the same time 😄

😄 wow, two for the price of one! Thanks again!

[DanielNoord]

@maread99 Could you check if there are any spaces after arg2 in your original example?

I can get this test to pass on main:

    @set_config(default_docstring_type="numpy")
    def test_no_type_func_params_in_numpy_docstring(self) -> None:
        """Example of a function with NumPy style parameter without type annotation
        documentation in the docstring
        """
        node = astroid.extract_node(
            """
        def func(arg1: bool, arg2: bool):
            '''Return args.

            Parameters
            ----------
            arg1 : bool
                arg1

            arg2
                arg2
                
            Returns
            ----------
            bool
            bool
            '''
            return arg1, arg2
        """
        )
        with self.assertNoMessages():
            self.checker.visit_functiondef(node)

If I add a space after the arg2 docstring it starts to fail with the error you report.

Please let me know if I missed anything in this test, but I feel like this fits your example.

Edit: Never mind. Managed to make it fail :)

[maread99]

Edit: Never mind. Managed to make it fail :)

I checked anyway - no trailing whitespace I'm afraid (I format to black quite religiously).

[DanielNoord]

I looked into it yesterday. This is dependent on quite complicated regex patterns that I did not at look before. Sadly I won't be able to fix this as easily as I hoped. I will take another look next week!

[maread99]

Looks like you got there earlier than anticipated! Thank you for resolving this!

[DanielNoord]

Yeah I couldn't let an incomprehensible regex pattern ruin my Saturday 😄

[Pierre-Sassoulas]

Daniel you're making our issue number trend look like the 2008 crash on the stock market with all those incomprehensible regex fixes lately. 😄

[DanielNoord]

I actually don't mind working with regex (I know, weird..). The problem is that the docstring checker uses a lot of nested patterns which makes it difficult to see what is actually catching what.
The other tagged issue should be more straightforward though!