Tool to compare function signature to docstring

user_8335924 0
Viewed 608

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.

visual-studio-code signature docstring code-documentation python
2 Answers

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. enter image description here https://marketplace.visualstudio.com/items?itemName=JeppeRask.pydoctest

user_37176910

I was trying to find the same, so I wrote docsig

pip install docsig

then just run docsig . and it will check this for you

/path/to/project
-----------------------
def function(✖*args) -> ✓List[str]:
    """...

    :param None: ✖
    :return: ✓
    """

E103: parameters missing

There are 8 other errors so far

user_133166710
Related