False negative differing-type-doc for Google-style docstring

[void-rooster]

Bug description

"""Fake function."""

from shapely.geometry import Point

def test(x: Point) -> int:
    """Fake function.

    Args:
        x (tuple[float, float]): X.

    Returns:
        int: Integer.
    """
    return 5

Command used

pylint --load-plugins=pylint.extensions.docparams test.py

Pylint output

************* Module xxxxxx
test.py: 5: [W0613 (unused-argument), test] Unused argument 'x'

------------------------------------------------------------------
Your code has been rated at 6.67/10 (previous run: 6.67/10, +0.00)

Expected behavior

Possible duplicate of #6478 . I expect the difference between Point in function signature and tuple[float, float] in documentation to raise differing-type-doc.

Pylint version

pylint 3.3.4
astroid 3.3.8
Python 3.9.21
[GCC 10.2.1 20210110]

[mbyrnepr2]

I think this is a feature request and not a bug. From what I can tell it appears the idea behind differing-type-doc is to highlight when the name X in the docstring is missing from the function parameters. An example being if you make a typo in the naming of the name in the docstring and it differs from what is listed in the parameters.
There's nothing in the code that factors in the type of the names and how they differ.

[void-rooster]

I think there is a typo in the documentation of differing-type-doc, as there is differing-param-doc that catches differences in parameter name. Note that in the differing-type-doc documentation, there are two errors in the problematic code: x in the function signature is referred to as xy in the docstring, and y has type int in the function signature and type str in the docstring.

[mbyrnepr2]

My understanding is that both of these messages, for type and param, relate to name differences.
I agree there’s a typo in the differing-type-doc because it gives the impression that the types themselves are checked for consistency (but I don’t think they actually are).

[void-rooster]

the example problematic code on differing-param-doc doesn't raise an error.

"""Fake function."""


def add(x, y):
    """Add two numbers.

    :param int x: x value.
    :param int z: z value.
    """

    return x + y

ubuntu@xxxx$ pylint --load-plugins=pylint.extensions.docparams test.py

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

[void-rooster]

I don't follow what you mean by name differences. the type annotation in the function signature in the initial bug report is Point, so I expect the following to not raise differing-type-doc, as the string "Point" appears as the type annotation in the docstring:

def test(x: Point) -> int:
    """Fake function.

    Args:
        x (Point): Value.

    Returns:
        int: Integer.
    """
    return 5

[mbyrnepr2]

The code explains it a bit more clearly than the docs I think: https://github.com/pylint-dev/pylint/blob/main/pylint/extensions/docparams.py#L510-L511
Check that all parameters are consistent with the parameters mentioned
in the parameter documentation (e.g. the Sphinx tags 'param' and 'type').

So, if you have a parameter X in the signature of the function but it is named XY in the docstring then it would raise the warning. And that happens for both type and param tags: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#:~:text=The%20Sphinx%20docstring%20format,-In%20general%2C%20a&text=A%20pair%20of%20%3Aparam%3A%20and,values%20returned%20by%20our%20code.

So, I'm saying that type annotations are not factored into these checkers at all. It sounds like it could be a new check.

[void-rooster]

So, if you have a parameter X in the signature of the function but it is named XY in the docstring then it would raise the warning.

does this comment convince you that the check is not happening?

[void-rooster]

oh I see. I will argue that the documentation should be clarified, as this Sphinx-style docstring raises differing-type-doc:

"""Fake function."""


def add(x: int, y: int):
    """Add two numbers.

    :param x: x value.
    :type x: int
    :param y: y value.
    :type z: int

    :return: Sum.
    """

    return x + y

I don't use Sphinx-style docstrings, always Google. In Google style there is no linebreak between the parameter definition and the type definition for the parameter, so it's basically impossible to raise differing-type-doc.

[mbyrnepr2]

"""Fake function."""

def add(x, y):
"""Add two numbers.

:param int x: x value.
:param int z: z value.
"""

return x + y

For this one I do see some warnings (I wonder are our configs different in some way here):

(venv312) markbyrne@Marks-Air-2 programming % cat x.py 
"""Fake function."""


def add(x, y):
    """Add two numbers.

    :param int x: x value.
    :param int z: z value.
    """

    return x + y
(venv312) markbyrne@Marks-Air-2 programming % pylint x.py --load-plugins=pylint.extensions.docparams
************* Module x
x.py:4:0: W9015: "y" missing in parameter documentation (missing-param-doc)
x.py:4:0: W9016: "y" missing in parameter type documentation (missing-type-doc)
x.py:4:0: W9017: "z" differing in parameter documentation (differing-param-doc)
x.py:4:0: W9018: "z" differing in parameter type documentation (differing-type-doc)

------------------------------------------------------------------
Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)

(venv312) markbyrne@Marks-Air-2 programming % 

[void-rooster]

yup it's something in my .pylintrc