Improve documentation of ``docparams`` extension and fix tests (#5095)

This closes #4136

2 files changed, 86 insertions, 1 deletions

diff --git a/pylint/extensions/docparams.rst b/pylint/extensions/docparams.rst
index e46c4dcd7..e9e0eea00 100644
--- a/pylint/extensions/docparams.rst
+++ b/pylint/extensions/docparams.rst
@@ -90,6 +90,9 @@ You'll be notified of **missing parameter documentation** but also of
 **naming inconsistencies** between the signature and the documentation which
 often arise when parameters are renamed automatically in the code, but not in
 the documentation.
+**Note:** by default docstrings of private and magic methods are not checked.
+To change this behaviour (for example, to also check ``__init__``) add
+``no-docstring-rgx=^(?!__init__$)_`` to the ``BASIC`` section of your ``.pylintrc``.
 
 Constructor parameters can be documented in either the class docstring or
 the ``__init__`` docstring, but not both::
diff --git a/tests/extensions/test_check_docs.py b/tests/extensions/test_check_docs.py
index 04919c27b..0d50b8535 100644
--- a/tests/extensions/test_check_docs.py
+++ b/tests/extensions/test_check_docs.py
@@ -42,7 +42,7 @@ class TestParamDocChecker(CheckerTestCase):
     CHECKER_CLASS = DocstringParameterChecker
     CONFIG = {
         "accept_no_param_doc": False,
-        "no_docstring_rgx": "",
+        "no_docstring_rgx": re.compile("^$"),
         "docstring_min_length": -1,
     }
 
@@ -2344,6 +2344,88 @@ class TestParamDocChecker(CheckerTestCase):
         with self.assertNoMessages():
             self.checker.visit_functiondef(node)
 
+    def test_all_docstring_rgx(self) -> None:
+        """Function that matches "check all functions" 'no-docstring-rgx' config option
+        No error message is emitted.
+        """
+        node = astroid.extract_node(
+            """
+        #pylint disable=missing-module-docstring, too-few-public-methods,
+        class MyClass:
+            def __init__(self, my_param: int) -> None:
+                '''
+                My init docstring
+                :param my_param: My first param
+                '''
+        """
+        )
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node.body[0])
+
+    def test_fail_empty_docstring_rgx(self) -> None:
+        """Function that matches "check all functions" 'no-docstring-rgx' config option
+        An error message is emitted.
+        """
+        node = astroid.extract_node(
+            """
+        #pylint disable=missing-module-docstring, too-few-public-methods,
+        class MyClass:
+            def __init__(self, my_param: int) -> None:
+                '''
+                My init docstring
+                '''
+        """
+        )
+        with self.assertAddsMessages(
+            MessageTest(
+                msg_id="missing-param-doc", node=node.body[0], args=("my_param",)
+            ),
+        ):
+            self.checker.visit_functiondef(node.body[0])
+
+    @set_config_directly(no_docstring_rgx=re.compile("^(?!__init__$)_"))
+    def test_fail_docparams_check_init(self) -> None:
+        """Check that __init__ is checked correctly, but other private methods aren't"""
+        node = astroid.extract_node(
+            """
+        #pylint disable=missing-module-docstring, too-few-public-methods,
+        class MyClass:
+            def __init__(self, my_param: int) -> None:
+                '''
+                My init docstring
+                '''
+
+            def _private_method(self, my_param: int) -> None:
+                '''
+                My private method
+                '''
+        """
+        )
+        with self.assertAddsMessages(
+            MessageTest(
+                msg_id="missing-param-doc", node=node.body[0], args=("my_param",)
+            )
+        ):
+            self.checker.visit_functiondef(node.body[0])
+
+    @set_config_directly(no_docstring_rgx=re.compile(""))
+    def test_no_docstring_rgx(self) -> None:
+        """Function that matches "check no functions" 'no-docstring-rgx' config option
+        No error message is emitted.
+        """
+        node = astroid.extract_node(
+            """
+        #pylint disable=missing-module-docstring, too-few-public-methods,
+        class MyClass:
+            def __init__(self, my_param: int) -> None:
+                '''
+                My init docstring
+                '''
+        """
+        )
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node.body[0])
+
     @set_config_directly(docstring_min_length=3)
     def test_skip_docstring_min_length(self) -> None:
         """Example of a function that is less than 'docstring-min-length' config option