Fix accept-no-yields/return-doc for partially correct docstrings

Author: DanielNoord

ChangeLog

@@ -19,6 +19,11 @@ Release date: TBA
 
 * Fix exception when pyreverse parses ``property function`` of a class.
 
+* Fix ``accept-no-yields-doc`` and ``accept-no-return-doc`` not allowing missing ``yield`` or
+  ``return`` documentation when a docstring is partially correct
+
+  Closes #5223
+
 * Add an optional extension ``consider-using-any-or-all`` : Emitted when a ``for`` loop only
   produces a boolean and could be replaced by ``any`` or ``all`` using a generator. Also suggests
   a suitable any or all statement.

doc/whatsnew/2.12.rst

@@ -77,6 +77,11 @@ Other Changes
 
   Closes #5178
 
+* Fix ``accept-no-yields-doc`` and ``accept-no-return-doc`` not allowing missing ``yield`` or
+  ``return`` documentation when a docstring is partially correct
+
+  Closes #5223
+
 * Fix ``simplify-boolean-expression`` when condition can be inferred as False.
 
   Closes #5200

pylint/extensions/docparams.py

@@ -322,13 +322,14 @@ def visit_return(self, node: nodes.Return) -> None:
         if not utils.returns_something(node):
             return
 
+        if self.config.accept_no_return_doc:
+            return
+
         func_node = node.frame()
         if not isinstance(func_node, astroid.FunctionDef):
             return
 
         doc = utils.docstringify(func_node.doc, self.config.default_docstring_type)
-        if not doc.is_valid() and self.config.accept_no_return_doc:
-            return
 
         is_property = checker_utils.decorated_with_property(func_node)
 
@@ -342,13 +343,14 @@ def visit_return(self, node: nodes.Return) -> None:
             self.add_message("missing-return-type-doc", node=func_node)
 
     def visit_yield(self, node: nodes.Yield) -> None:
+        if self.config.accept_no_yields_doc:
+            return
+
         func_node = node.frame()
         if not isinstance(func_node, astroid.FunctionDef):
             return
 
         doc = utils.docstringify(func_node.doc, self.config.default_docstring_type)
-        if not doc.is_valid() and self.config.accept_no_yields_doc:
-            return
 
         if doc.supports_yields:
             doc_has_yields = doc.has_yields()

tests/extensions/test_check_docs.py

@@ -1886,6 +1886,7 @@ def foo(self) -> int: #@
         with self.assertNoMessages():
             self.checker.visit_return(node)
 
+    @set_config(accept_no_return_doc="no")
     def test_finds_missing_property_return_type_sphinx(self) -> None:
         """Example of a property having missing return documentation in
         a Sphinx style docstring
@@ -1929,6 +1930,7 @@ def foo(self) -> int: #@
         with self.assertNoMessages():
             self.checker.visit_return(node)
 
+    @set_config(accept_no_return_doc="no")
     def test_finds_missing_property_return_type_google(self) -> None:
         """Example of a property having return documentation in
         a Google style docstring
@@ -1952,6 +1954,7 @@ def foo(self): #@
         ):
             self.checker.visit_return(node)
 
+    @set_config(accept_no_return_doc="no")
     def test_finds_missing_property_return_type_numpy(self) -> None:
         """Example of a property having return documentation in
         a numpy style docstring
@@ -1977,6 +1980,7 @@ def foo(self): #@
         ):
             self.checker.visit_return(node)
 
+    @set_config(accept_no_return_doc="no")
     def test_ignores_non_property_return_type_sphinx(self) -> None:
         """Example of a class function trying to use `type` as return
         documentation in a Sphinx style docstring
@@ -1998,6 +2002,7 @@ def foo(self): #@
         ):
             self.checker.visit_return(node)
 
+    @set_config(accept_no_return_doc="no")
     def test_ignores_non_property_return_type_google(self) -> None:
         """Example of a class function trying to use `type` as return
         documentation in a Google style docstring
@@ -2021,6 +2026,7 @@ def foo(self): #@
         ):
             self.checker.visit_return(node)
 
+    @set_config(accept_no_return_doc="no")
     def test_ignores_non_property_return_type_numpy(self) -> None:
         """Example of a class function trying to use `type` as return
         documentation in a numpy style docstring
@@ -2046,6 +2052,7 @@ def foo(self): #@
         ):
             self.checker.visit_return(node)
 
+    @set_config(accept_no_return_doc="no")
     def test_non_property_annotation_return_type_numpy(self) -> None:
         """Example of a class function trying to use `type` as return
         documentation in a numpy style docstring

tests/extensions/test_check_return_docs.py

@@ -68,6 +68,7 @@ def my_func(self):
         with self.assertNoMessages():
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_partial_sphinx_returns(self) -> None:
         node = astroid.extract_node(
             '''
@@ -100,6 +101,7 @@ def my_func(self) -> bool:
         with self.assertNoMessages():
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_partial_sphinx_returns_type(self) -> None:
         node = astroid.extract_node(
             '''
@@ -117,6 +119,7 @@ def my_func(self):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_missing_sphinx_returns(self) -> None:
         node = astroid.extract_node(
             '''
@@ -136,6 +139,7 @@ def my_func(self, doc_type):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_partial_google_returns(self) -> None:
         node = astroid.extract_node(
             '''
@@ -154,6 +158,7 @@ def my_func(self):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_partial_google_returns_type(self) -> None:
         node = astroid.extract_node(
             '''
@@ -172,6 +177,7 @@ def my_func(self):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_missing_google_returns(self) -> None:
         node = astroid.extract_node(
             '''
@@ -191,6 +197,7 @@ def my_func(self, doc_type):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_partial_numpy_returns_type(self) -> None:
         node = astroid.extract_node(
             '''
@@ -215,6 +222,7 @@ def my_func(self, doc_type):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warn_missing_numpy_returns(self) -> None:
         node = astroid.extract_node(
             '''
@@ -441,6 +449,7 @@ def my_func(self):
         with self.assertNoMessages():
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warns_sphinx_return_list_of_custom_class_without_description(self) -> None:
         node = astroid.extract_node(
             '''
@@ -458,6 +467,7 @@ def my_func(self):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warns_google_return_list_of_custom_class_without_description(self) -> None:
         node = astroid.extract_node(
             '''
@@ -476,6 +486,7 @@ def my_func(self):
         ):
             self.checker.visit_return(return_node)
 
+    @set_config(accept_no_return_doc="no")
     def test_warns_numpy_return_list_of_custom_class_without_description(self) -> None:
         node = astroid.extract_node(
             '''

tests/extensions/test_check_yields_docs.py

@@ -64,6 +64,7 @@ def my_func(self):
         with self.assertNoMessages():
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warn_partial_sphinx_yields(self) -> None:
         node = astroid.extract_node(
             '''
@@ -81,6 +82,7 @@ def my_func(self):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warn_partial_sphinx_yields_type(self) -> None:
         node = astroid.extract_node(
             '''
@@ -98,6 +100,7 @@ def my_func(self):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warn_missing_sphinx_yields(self) -> None:
         node = astroid.extract_node(
             '''
@@ -117,6 +120,7 @@ def my_func(self, doc_type):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warn_partial_google_yields(self) -> None:
         node = astroid.extract_node(
             '''
@@ -135,6 +139,7 @@ def my_func(self):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warn_partial_google_yields_type(self) -> None:
         node = astroid.extract_node(
             '''
@@ -153,6 +158,7 @@ def my_func(self):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warn_missing_google_yields(self) -> None:
         node = astroid.extract_node(
             '''
@@ -172,6 +178,7 @@ def my_func(self, doc_type):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warn_missing_numpy_yields(self) -> None:
         node = astroid.extract_node(
             '''
@@ -334,6 +341,7 @@ def my_func(self):
         with self.assertNoMessages():
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warns_sphinx_yield_list_of_custom_class_without_description(self) -> None:
         node = astroid.extract_node(
             '''
@@ -351,6 +359,7 @@ def my_func(self):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warns_google_yield_list_of_custom_class_without_description(self) -> None:
         node = astroid.extract_node(
             '''
@@ -369,6 +378,7 @@ def my_func(self):
         ):
             self.checker.visit_yield(yield_node)
 
+    @set_config(accept_no_yields_doc="no")
     def test_warns_numpy_yield_list_of_custom_class_without_description(self) -> None:
         node = astroid.extract_node(
             '''