Arguments wrongly listed as missing based on type

[ezwelty]

I believe I've stumbled into a bug, or at least a usability issue.

Say we have the following test.py:

"""Module docstring."""


def f(x: int, y: int, z: int) -> None:
    """
    Run f().

    Parameters
    ----------
    y
        y
    z
        z
    """
    pass

Running pydoclint with --arg-type-hints-in-docstring False results in the following:

• DOC101: Function f: Docstring contains fewer arguments than in function signature.
• DOC103: Function f: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [x: int, y: int, z: int]. Arguments in the docstring but not in the function signature: [y: , z: ].

It seems that the latter part should just be Arguments in the function signature but not in the docstring: [x: int].

Adding x to the docstring removes all errors. Likewise, adding --arg-type-hints-in-signature False and removing the type annotations results in the expected error Arguments in the function signature but not in the docstring: [x: ].

[jsh9]

Hi @ezwelty , this is because there needs to be : in the arg list of the docstring.

Please check out the note in this error message:

DOC103: Function f: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ).

[ezwelty]

@jsh9 Did you maybe misread my issue? The : is omitted when a type is not given. See the numpy style guide (https://numpydoc.readthedocs.io/en/latest/format.html#parameters). With the following file and --arg-type-hints-in-docstring False, no errors are returned (as expected).

"""Module docstring."""


def f(x: int, y: int, z: int) -> None:
    """
    Run f().

    Parameters
    ----------
    x
        x
    y
        y
    z
        z
    """
    pass

[jsh9]

Thanks for the clarification!

I made a code change and now your test case should produce the following error message:

pydoclint/tests/test_main.py

Lines 1090 to 1097 in bef414f

	[
	'DOC101: Function `f`: Docstring contains fewer arguments than in function '
	'signature. ',
	'DOC103: Function `f`: Docstring arguments are different from function '
	'arguments. (Or could be other formatting issues: '
	'https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). '
	'Arguments in the function signature but not in the docstring: [x: int].',
	],

Note that the error message shows [x: int] rather than [x: ] -- this is for backward compatibility purposes.

[jsh9]

The code change is published as v0.3.4 to PyPI.