Tool to compare function signature to docstring

Question

Is there a tool that can check if the arguments listed in the docstring match the signature of the function call? It should be able to deal with numpy-style docstrings. I am regularly using R CMD CHECK, which finds documentation/code mismatches in R and this is quite helpful. It would be very good to have something similar in Python, but I did not find anything yet.

Answer 1

I just created a tool to achieve this, called pydoctest.

It will attempt to infer the types in your docstrings (not just lexically compare) and report back on mismatches between number of arguments, argument-names, argument-types, return-types, (optionally) throw error if lacking docstring and more.

It currently supports google, sphinx and numpy docstring format, but can rather easily be extended with other formats.

Example:

def func_type_mismatch(self, a: int) -> int:
    """[summary]

    Args:
        a (float): [description]        <-- float is not int

    Returns:
        int: [description]
    """
    pass

Running pydoctest on this function, gives this output:

Function: <function IncorrectTestClass.func_type_mismatch at 0x7f9a8b52c8c8> FAIL | Argument type differ. Argument 'a' was expected (from signature) to have type '<class 'int'>', but has (in docs) type '<class 'float'>'

Edit (June 2021): I've started the development of a vscode-extension that uses and highlights the errors. https://marketplace.visualstudio.com/items?itemName=JeppeRask.pydoctest