Enforce docparams consistently when docstring is not present (pylint-…

…dev#3916)

* fix pylint-dev#2738

* doc updates

* add functional tests

* fix formattting

* fix formatting

CONTRIBUTORS.txt

@@ -436,4 +436,6 @@ contributors:
 
 * Frank Harrison (doublethefish): contributor
 
-* Matthew Suozzo
+* Logan Miller (komodo472): contributor
+
+* Matthew Suozzo: contributor

ChangeLog

@@ -78,6 +78,10 @@ Release date: TBA
 
   Close #3800
 
+* Enforce docparams consistently when docstring is not present
+
+  Close #2738
+
 * Fix ``duplicate-code`` false positive when lines only contain whitespace and non-alphanumeric characters (e.g. parentheses, bracket, comman, etc.)
 
 * Improve lint message for `singleton-comparison` with bools

pylint/extensions/docparams.py

@@ -20,6 +20,8 @@
 
 """Pylint plugin for checking in Sphinx, Google, or Numpy style docstrings
 """
+import re
+
 import astroid
 
 from pylint.checkers import BaseChecker
@@ -205,6 +207,18 @@ def visit_functiondef(self, node):
         :type node: :class:`astroid.scoped_nodes.Function`
         """
         node_doc = utils.docstringify(node.doc, self.config.default_docstring_type)
+
+        # skip functions that match the 'no-docstring-rgx' config option
+        no_docstring_rgx = get_global_option(self, "no-docstring-rgx")
+        if no_docstring_rgx and re.match(no_docstring_rgx, node.name):
+            return
+
+        # skip functions smaller than 'docstring-min-length'
+        lines = checker_utils.get_node_last_lineno(node) - node.lineno
+        max_lines = get_global_option(self, "docstring-min-length")
+        if max_lines > -1 and lines < max_lines:
+            return
+
         self.check_functiondef_params(node, node_doc)
         self.check_functiondef_returns(node, node_doc)
         self.check_functiondef_yields(node, node_doc)

tests/extensions/test_check_docs.py

@@ -32,7 +32,11 @@ class TestParamDocChecker(CheckerTestCase):
     """Tests for pylint_plugin.ParamDocChecker"""
 
     CHECKER_CLASS = DocstringParameterChecker
-    CONFIG = {"accept_no_param_doc": False}
+    CONFIG = {
+        "accept_no_param_doc": False,
+        "no_docstring_rgx": "",
+        "docstring_min_length": -1,
+    }
 
     def test_missing_func_params_in_sphinx_docstring(self):
         """Example of a function with missing Sphinx parameter documentation in
@@ -2296,3 +2300,37 @@ def foo(self, arg, _, _ignored): #@
             Message(msg_id="useless-type-doc", node=node, args=("_",)),
         ):
             self.checker.visit_functiondef(node)
+
+    @set_config(no_docstring_rgx=r"^_(?!_).*$")
+    def test_skip_no_docstring_rgx(self):
+        """Example of a function that matches the default 'no-docstring-rgx' config option
+
+        No error message is emitted.
+        """
+        node = astroid.extract_node(
+            """
+        def _private_function_foo(x, y):
+            '''docstring ...
+
+            missing parameter documentation'''
+            pass
+        """
+        )
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node)
+
+    @set_config(docstring_min_length=3)
+    def test_skip_docstring_min_length(self):
+        """Example of a function that is less than 'docstring-min-length' config option
+
+        No error message is emitted.
+        """
+        node = astroid.extract_node(
+            """
+        def function_foo(x, y):
+            '''function is too short and is missing parameter documentation'''
+            pass
+        """
+        )
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node)

tests/functional/f/fixture_docparams_missing.py

@@ -0,0 +1,11 @@
+"""Fixture for testing missing documentation in docparams."""
+
+
+def _private_func(param1):
+    if param1:
+        raise Exception('Example')
+    return param1
+
+
+def _private_func2(param1):
+    yield param1

tests/functional/f/fixture_docparams_missing.rc

@@ -0,0 +1,8 @@
+[MASTER]
+load-plugins = pylint.extensions.docparams
+
+[BASIC]
+accept-no-param-doc = no
+accept-no-raise-doc = no
+accept-no-return-doc = no
+accept-no-yields-doc = no