False positive (?) DAR101 for argument lists with blank lines

[ezwelty]

For example, Sphinx (RST) requires a blank line before and after a bullet list. However, this leads to darglint missing all of the arguments that follow these blank lines.

Here is an example where the first argument has a bullet list, so the second argument is missed by darglint. The Google style docs do not mention blank lines being allowed or not, but for what it's worth, this is parsed as expected by sphinx.ext.napoleon.

test.py

def function(x, y):
    """
    A function.

    Args:
        x (int): A very long description.

            - Either this.
            - Or that.

        y (int): Another argument.
    """
    pass

darglint -v 2 test.py
# test.py:function:4: DAR101: Missing parameter(s) in Docstring: - y

[terrencepreilly]

Sorry about not replying to this for a while, I've been rather busy. Yes, this is a limitation in darglint. This occurs because darglint splits by blank to determine sections -- when an argument has a blank line, it is interpreted as a new section. See here for the responsible function in Sphinx, for an example. I chose to do this because without breaking down the docstring into sections, the runtime degrades quickly. (Before this change, some docstrings took ~30 seconds to parse.)

This can probably be solved in a couple ways. Either by running a separate parser over the tokens to first discover sections, or by finding a better heuristic for determining sections. I'll mark this as a bug, but I don't expect to get to it any time soon, just because it'll be a bigger thing to tackle.

[ezwelty]

In Google and Numpy style, section headers follow a strict formatting. Can these formats be represented by your existing tokens?

• google: \n(Arguments|...)\:\n\t -> NEWLINE (ARGUMENTS | ... ) COLON NEWLINE INDENT ?
• numpy: \n(Parameters|...)\n\-+\n-> NEWLINE (ARGUMENTS | ... ) NEWLINE HEADER NEWLINE ?

From what I understand of Sphinx style, it does not have a concept of sections, but rather uses directives to tag each line with meaning.

[muxator]

Hi, I understand darglint is not actively maintained anymore, and this would not be a trivial change (thank you, btw).

I just wanted to confirm that - as of darglint v1.8.1 - this problem is still present.