From 8e15c1dd9d0dc07cb9794353a32cd37d57f2d569 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Sat, 13 Nov 2021 00:44:22 +0200 Subject: Fix ``accept-no-yields/return-doc`` for partially correct docstrings --- ChangeLog | 5 +++++ doc/whatsnew/2.12.rst | 5 +++++ pylint/extensions/docparams.py | 10 ++++++---- tests/extensions/test_check_docs.py | 7 +++++++ tests/extensions/test_check_return_docs.py | 11 +++++++++++ tests/extensions/test_check_yields_docs.py | 10 ++++++++++ 6 files changed, 44 insertions(+), 4 deletions(-) diff --git a/ChangeLog b/ChangeLog index 253a35fae..1403acbcd 100644 --- a/ChangeLog +++ b/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. diff --git a/doc/whatsnew/2.12.rst b/doc/whatsnew/2.12.rst index 919371046..be99f68d9 100644 --- a/doc/whatsnew/2.12.rst +++ b/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 diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py index 17ec303a9..922921774 100644 --- a/pylint/extensions/docparams.py +++ b/pylint/extensions/docparams.py @@ -322,13 +322,14 @@ class DocstringParameterChecker(BaseChecker): 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 @@ class DocstringParameterChecker(BaseChecker): 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() diff --git a/tests/extensions/test_check_docs.py b/tests/extensions/test_check_docs.py index 5fdbc0ee3..5455bea67 100644 --- a/tests/extensions/test_check_docs.py +++ b/tests/extensions/test_check_docs.py @@ -1886,6 +1886,7 @@ class TestParamDocChecker(CheckerTestCase): 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 @@ class TestParamDocChecker(CheckerTestCase): 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 @@ class TestParamDocChecker(CheckerTestCase): ): 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 @@ class TestParamDocChecker(CheckerTestCase): ): 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 @@ class TestParamDocChecker(CheckerTestCase): ): 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 @@ class TestParamDocChecker(CheckerTestCase): ): 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 @@ class TestParamDocChecker(CheckerTestCase): ): 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 diff --git a/tests/extensions/test_check_return_docs.py b/tests/extensions/test_check_return_docs.py index 6c73a188f..64b56434d 100644 --- a/tests/extensions/test_check_return_docs.py +++ b/tests/extensions/test_check_return_docs.py @@ -68,6 +68,7 @@ class TestDocstringCheckerReturn(CheckerTestCase): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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 @@ class TestDocstringCheckerReturn(CheckerTestCase): ): 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( ''' diff --git a/tests/extensions/test_check_yields_docs.py b/tests/extensions/test_check_yields_docs.py index e714b3c61..e4ae70770 100644 --- a/tests/extensions/test_check_yields_docs.py +++ b/tests/extensions/test_check_yields_docs.py @@ -64,6 +64,7 @@ class TestDocstringCheckerYield(CheckerTestCase): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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 @@ class TestDocstringCheckerYield(CheckerTestCase): ): 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( ''' -- cgit v1.2.1