False positive DOC203

[JohannesBuchner]

The following code I believe follows numpydoc style for the return documentation:

def list_documented_parameters(docstring: str):
    """Extract a list of documented parameters from docstring.

    Supports numpydoc-style, google-style and rst-style formats.

    Parameters
    ----------
    docstring: str
        documentation string

    Returns
    -------
    parameters: list
        names of the parameters
    types: list
        types of the parameters
    descriptions: list
        description of the parameters
    """
    return [], [], []

pydoclint gives:
"1: DOC203: Function list_documented_parameters return type(s) in docstring not consistent with the return annotation. Return annotation has 0 type(s); docstring return section has 3 type(s)."

Sorry if I misunderstood something.

Version:

$ pip install pydoclint
Collecting pydoclint
  Using cached pydoclint-0.5.9-py2.py3-none-any.whl.metadata (6.9 kB)
Requirement already satisfied: click>=8.1.0 in /usr/lib/python3/dist-packages (from pydoclint) (8.1.6)
Requirement already satisfied: docstring-parser-fork>=0.0.9 in /home/user/.local/lib/python3.12/site-packages (from pydoclint) (0.0.9)
Using cached pydoclint-0.5.9-py2.py3-none-any.whl (46 kB)
Installing collected packages: pydoclint
Successfully installed pydoclint-0.5.9

[jsh9]

Hi, you'd need to annotate the return types in the function signature.

def list_documented_parameters(docstring: str) -> tuple[list, list, list]:

[JohannesBuchner]

My code base actually does not have any annotations. I added one to the param arg to make the case simpler, but this error occurs with or without.

There is --arg-type-hints-in-signature=False but nothing corresponding for return types.

[JohannesBuchner]

If I may make a suggestion, the error code should be split into two:

1. one error code for "missing annotations".
2. one error code raised only when annotations are present and where "annotations are inconsistent". Presumably this should be DOC203.

This would allow me to ignore case (1), and give error messages that are precise.

A further possibility to consider is to change the code so that DOC203 is not raised when --arg-type-hints-in-signature=False.

[jsh9]

one error code for "missing annotations".

pydoclint doesn't check "missing annotations" but rather inconsistent annotations. For example, if annotations are missing in the function signature and in the docstring, pydoclint is fine with that.

A further possibility to consider is to change the code so that DOC203 is not raised when --arg-type-hints-in-signature=False.

So in your example, return type annotation rather than argument type annotation missing. "arg type hints in signature" only covers the arg list, not the return type.

[JohannesBuchner]

one error code for "missing annotations".

pydoclint doesn't check "missing annotations" but rather inconsistent annotations. For example, if annotations are missing in the function signature and in the docstring, pydoclint is fine with that.

I agree that this should be the behaviour.

A further possibility to consider is to change the code so that DOC203 is not raised when --arg-type-hints-in-signature=False.

So in your example, return type annotation rather than argument type annotation missing. "arg type hints in signature" only covers the arg list, not the return type.

Yes, it only refers to the arg list. Perhaps an additional flag is needed then.

[JohannesBuchner]

I am maintaining a code base that should work with old python versions, I cannot add annotations but would like to keep the informative docstring annotations. In my mind, unspecified annotations (that is, a lack of PEP 3107 annotations) are consistent and compatible with documented annotations.

[jsh9]

You can use the config option check-return-types to opt out of checking return types: https://jsh9.github.io/pydoclint/config_options.html#10---check-return-types-shortform--crt-default-true

Also, if you are dealing with a legacy code base, you can also use the "baseline" feature: https://jsh9.github.io/pydoclint/config_options.html#17---baseline