Avoiding rtype checks with typed code: No return type or annotation at ':return: ...

[ssbarnea]

Describe the bug

Once a library adopts type support is it very unlikely that the maintainers will want to duplicate the type information inside the docstrings. That duplication is a real maintenance issue and also a permanent source of bugs, as it is very easy to miss updating the docstring when changing the type.

I personally faced

griffe/src/griffe/docstrings/sphinx.py

Line 298 in 34bc108

_warn(docstring, 0, f"No return type or annotation at '{parsed_directive.line}'")

and I see no way to disable that kind of check.

That typing issue is so important that we are willing to switch to a different docstring format.

Currently we use sphinx for historical reasons and anything going towards markdown and less verbosity/duplication would be appealing.

[pawamoy]

Hello, thanks for the report!

I'm a bit confused: this warning is supposed to be emitted only when there is no annotation in the signature and no annotation in the docstring. But I didn't write the sphinx parser so maybe I misunderstood. At least that's how the warnings are supposed to work, and how they actually work in the other two parsers (google and numpy).

Could you show a code snippet that triggers the undesired warning?

[ssbarnea]

Here is an example that also includes the workaround for it https://github.com/ansible-community/molecule/pull/3811/files#diff-32abfdacc4eeea878460d3bf0ae452ab074ca485bab0b0a01b3bb07775ac002dR399-R630

Basically I removed the return for that one because it did not had any documentation and the type was already documented. I have few other similar places where for example I removed :rtype: line. Excuse the codebase of that project as it was not fully migrated to type, there is a LOT to add to it.

[pawamoy]

The example you linked actually confirms what I said above: https://github.com/ansible-community/molecule/pull/3811/files#diff-32abfdacc4eeea878460d3bf0ae452ab074ca485bab0b0a01b3bb07775ac002dR606-R628

You removed the :return: str line from the docstring of the inventory property, which does not have a return annotation (-> something). If I understand correctly, :return: is meant to give a description, while :rtype: is meant to give a type. Since :return: was present but neither the return annotation or the :rtype: directive were, a warning was emitted.

Or did I misunderstood the Sphinx directives?

[pawamoy]

Closing for now, feel free to reopen if needed.

[SnijderC]

This seems to happen with properties (@property decorated methods). Even if you add the type in the :return: directive, or :rtype:.

@property
def example(self) -> bool:
    """
    Property that returns True for explaining the issue. 
    
    :return: True
    """
    return True

@property
def example2(self) -> bool:
    """
    Property that returns True for explaining the issue. 
    
    :return bool: True
    """
    return True

@property
def example3(self) -> bool:
    """
    Property that returns True for explaining the issue. 
    
    :return: True
    :rtype: bool
    """
    return True

def example4(self) -> bool:
    """
    Property that returns True for explaining the issue. 
    
    :return: True
    """
    return True

Gives:

WARNING -  griffe: test.py:3: No return type or annotation at ':return: True'
WARNING -  griffe: test.py:12: No return type or annotation at ':return bool: True'
WARNING -  griffe: test.py:21: No return type or annotation at ':return: True'

Note the normal method does not trigger a warning, even without a Sphinx style type annotation.