Improve DOC403 message (#129)

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change Log
 
+## [0.4.2] - 2024-05-29
+
+- Changed
+
+  - Improved the violation message of DOC403 to remind users to add a return
+    annotation
+
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.4.1...0.4.2
+
 ## [0.4.1] - 2024-02-17
 
 - Fixed

pydoclint/utils/violation.py

@@ -39,6 +39,7 @@
     403: (  # noqa: PAR001
         'has a "Yields" section in the docstring, but there are no "yield"'
         ' statements, or the return annotation is not a Generator/Iterator/Iterable.'
+        ' (Or it could be because the function lacks a return annotation.)'
     ),
     404: 'yield type(s) in docstring not consistent with the return annotation.',
     405: (  # noqa: PAR001

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = pydoclint
-version = 0.4.1
+version = 0.4.2
 description = A Python docstring linter that checks arguments, returns, yields, and raises sections
 long_description = file: README.md
 long_description_content_type = text/markdown

tests/data/edge_cases/10_absent_return_anno/numpy.py

@@ -0,0 +1,35 @@
+# This edge case comes from: https://github.com/jsh9/pydoclint/issues/127
+
+from __future__ import annotations
+
+from typing import Iterable, Iterator
+
+
+def f1(args: list):
+    """ASDF
+
+    Arguments
+    ---------
+    args: list
+        args
+
+    Yields
+    ------
+    args: Iterable
+    """
+    yield from args
+
+
+def f2(args: list) -> Iterator[Iterable]:
+    """ASDF
+
+    Arguments
+    ---------
+    args: list
+        args
+
+    Yields
+    ------
+    args: Iterable
+    """
+    yield from args

tests/test_main.py

@@ -474,7 +474,8 @@ def testAllowInitDocstring(style: str) -> None:
         'because __init__() cannot yield anything ',
         'DOC403: Method `D.__init__` has a "Yields" section in the docstring, but '
         'there are no "yield" statements, or the return annotation is not a '
-        'Generator/Iterator/Iterable. ',
+        'Generator/Iterator/Iterable. (Or it could be because the function lacks a '
+        'return annotation.) ',
     ]
     assert list(map(str, violations)) == expected
 
@@ -499,7 +500,8 @@ def testYields(style: str) -> None:
         'section does not exist or has 0 type(s).',
         'DOC403: Method `A.method3` has a "Yields" section in the docstring, but '
         'there are no "yield" statements, or the return annotation is not a '
-        'Generator/Iterator/Iterable. ',
+        'Generator/Iterator/Iterable. (Or it could be because the function lacks a '
+        'return annotation.) ',
         'DOC402: Method `A.method6` has "yield" statements, but the docstring does '
         'not have a "Yields" section ',
         'DOC404: Method `A.method6` yield type(s) in docstring not consistent with '
@@ -528,7 +530,8 @@ def testYields(style: str) -> None:
         'DOC201: Method `A.zipLists2` does not have a return section in docstring ',
         'DOC403: Method `A.zipLists2` has a "Yields" section in the docstring, but '
         'there are no "yield" statements, or the return annotation is not a '
-        'Generator/Iterator/Iterable. ',
+        'Generator/Iterator/Iterable. (Or it could be because the function lacks a '
+        'return annotation.) ',
         'DOC404: Function `inner9a` yield type(s) in docstring not consistent with '
         'the return annotation. The yield type (the 0th arg in '
         'Generator[...]/Iterator[...]): str; docstring "yields" section types: '
@@ -541,7 +544,8 @@ def testYields(style: str) -> None:
         'DOC201: Method `A.method9c` does not have a return section in docstring ',
         'DOC403: Method `A.method9c` has a "Yields" section in the docstring, but '
         'there are no "yield" statements, or the return annotation is not a '
-        'Generator/Iterator/Iterable. ',
+        'Generator/Iterator/Iterable. (Or it could be because the function lacks a '
+        'return annotation.) ',
         'DOC404: Function `inner9c` yield type(s) in docstring not consistent with '
         'the return annotation. The yield type (the 0th arg in '
         'Generator[...]/Iterator[...]): str; docstring "yields" section types: '
@@ -1129,6 +1133,20 @@ def testNonAscii() -> None:
         ('08_return_section_parsing/google.py', {'style': 'google'}, []),
         ('09_double_quotes_in_Literal/google.py', {'style': 'google'}, []),
         ('09_double_quotes_in_Literal/numpy.py', {'style': 'numpy'}, []),
+        (
+            '10_absent_return_anno/numpy.py',
+            {'style': 'numpy'},
+            [
+                'DOC403: Function `f1` has a "Yields" section in the docstring, but there are '
+                'no "yield" statements, or the return annotation is not a '
+                'Generator/Iterator/Iterable. (Or it could be because the function lacks a '
+                'return annotation.) ',
+                'DOC404: Function `f1` yield type(s) in docstring not consistent with the '
+                'return annotation. Return annotation does not exist or is not '
+                'Generator[...]/Iterator[...]/Iterable[...], but docstring "yields" section '
+                'has 1 type(s).',
+            ],
+        ),
     ],
 )
 def testEdgeCases(