False positive of D417 (missing argument descriptions)

[stinovlas]

pydocstyle started reporting false positives of D417 in google convention on version 6.2.0 and later. Version 6.1.1 does not suffer the same problem. Consider following code:

def sum(a: int, b: int, c: int):
    """Sum three numbers.

    Args:
        a: First number.
        b: Second number.
        c: Third number.

    Some further details.
    """
    return a + b + c

When I run pydocstyle example.py --select=D417, I get the following output:

example.py:2 in public function `sum`:
        D417: Missing argument descriptions in the docstring (argument(s) b, c are missing descriptions in 'sum' docstring)

I'd expect no errors since all the arguments are properly listed in docstring.

[sambhav]

Likely related to https://github.com/PyCQA/pydocstyle/commit/1011866e6ea91a1fbcb4b01520d2a348becc7de1

[alanmcruickshank]

We're also experiencing this. For a live open source PR with an example in it see https://github.com/sqlfluff/sqlfluff/pull/4225 .

Agreed that problem does not exist in 6.1.1 but does exist in 6.2.0 and 6.2.1.

[stinovlas]

Likely related to 1011866

I tried to look into this and it seems that problem is actually deeper than just this commit. It seems that Some further details. is considered to be part of Args section context. That causes the bad recognition, but I think that this issue should be solved higher in the chain so that following string is not appended to the section at all.

[stinovlas]

I'm thinking about how to resolve this. With google style, it's quite easy to recognize that Some further details. is not part of the Args section, due to its indent. On the other hand, in numpy convention, we can't do that, because it's not in general indented. Also, google docstring style only provides examples with multiline description before any section although it doesn't expressively prohibit to place this description in other places.

[stinovlas]

I proposed a solution that should fix this for all indent-driven conventions and not break any non-indented ones (like numpy). Not great, not terrible. See #619.

[sambhav]

Should be fixed in 6.2.2 which was just released. Please test.

[stinovlas]

Works like a charm. Thank you for being so fast and responsive :slightly_smiling_face:.