Bug: Requires Return Section in Docstring When None Is the Return Type

[rbebb]

I noticed that docstrings require a return section even when the return type is None, but this only occurs when there are parameters in the function. The error does not occur if there are zero parameters in the function. Also, the docstrings use Google style.

Example (Error):

def test(text: str) -> None:
    """Run test.

    Args:
        text (str): Text for the function
    """

Example (Pass):

def test() -> None:
    """Run test.

    """

[jsh9]

Hi @rbebb ,

Thank you for reporting this issue.

docstrings require a return section even when the return type is None

I implemented this check because this seems to be the convention of the numpy-style docstring:

"""
Parameters
-----------
arg1 : int
    Something
arg2 : str
    Something else

Returns
--------
None
"""

I can add a configurable option that allows us to not add a "returns" section when the function returns None (implicitly or explicitly).

but this only occurs when there are parameters in the function

Yep, this is an intended behavior.

By pydoclint's default, the option --skip-checking-short-docstrings is set to True. Short docstrings (not an "official" term though) are those only with a description but no "args" or "returns" sections.

This allows us to be a bit "lazy" for some self-explanatory functions/methods.

But as soon as we add an "args" section in our docstring, it is no longer a "short docstring", which is why pydoclint starts to check the existence of a "Returns" section.

[jsh9]

Hi @rbebb , I've fixed this issue in a PR. This fix will be shipped with the newest release in a day or two.

[jsh9]

Hi @rbebb , I just published version 0.0.5, which includes this fix.

[rbebb]

Thank you very much! I appreciate you making that change!