Extend support for detecting missing arguments in Numpy style docstrings (#407)

* Remove Parameters from valid Google section names

Google docstrings should document their arguments in the Args section
not the Parameters section.

See http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings

* Add support for checking missing parameters in Numpy docstrings

Fixes #394

This adds support for checking missing arguments in Numpy docstrings.

* Clarify D417 error about missing descriptions and add tests for it

D417 is raised even if that parameter is present in the docstring,
but has an empty description.

* Fix tests

Author: sambhav

docs/release_notes.rst

@@ -15,6 +15,9 @@ New Features
 
 * Extend support for detecting missing arguments in Google style
   docstrings to method calls (#384).
+* Extend support for detecting missing argument description in Numpy style
+  docstrings (#407).
+
 
 Bug Fixes
 

src/pydocstyle/checker.py

@@ -72,8 +72,6 @@ class ConventionChecker:
         'Methods',
         'Note',
         'Notes',
-        'Other Parameters',
-        'Parameters',
         'Return',
         'Returns',
         'Raises',
@@ -678,6 +676,48 @@ def _check_numpy_section(cls, docstring, definition, context):
         if suffix:
             yield violations.D406(capitalized_section, context.line.strip())
 
+        if capitalized_section == "Parameters":
+            yield from cls._check_parameters_section(docstring, definition, context)
+
+    @staticmethod
+    def _check_parameters_section(docstring, definition, context):
+        """D417: `Parameters` section check for numpy style.
+
+        Check for a valid `Parameters` section. Checks that:
+            * The section documents all function arguments (D417)
+                except `self` or `cls` if it is a method.
+
+        """
+        docstring_args = set()
+        section_level_indent = leading_space(context.line)
+        content = context.following_lines
+        for current_line, next_line in zip(content, content[1:]):
+            # All parameter definitions in the Numpy parameters
+            # section must be at the same indent level as the section
+            # name.
+            # Also, we ensure that the following line is indented,
+            # and has some string, to ensure that the parameter actually
+            # has a description.
+            # This means, this is a parameter doc with some description
+            if ((leading_space(current_line) == section_level_indent)
+                and (len(leading_space(next_line)) > len(leading_space(current_line)))
+                and next_line.strip()):
+                # In case the parameter has type definitions, it
+                # will have a colon
+                if ":" in current_line:
+                    parameters, parameter_type = current_line.split(":", 1)
+                # Else, we simply have the list of parameters defined
+                # on the current line.
+                else:
+                    parameters = current_line.strip()
+                # Numpy allows grouping of multiple parameters of same
+                # type in the same line. They are comma separated.
+                parameter_list = parameters.split(",")
+                for parameter in parameter_list:
+                    docstring_args.add(parameter.strip())
+        yield from ConventionChecker._check_missing_args(docstring_args, definition)
+
+
     @staticmethod
     def _check_args_section(docstring, definition, context):
         """D417: `Args` section checks.
@@ -692,6 +732,19 @@ def _check_args_section(docstring, definition, context):
             match = ConventionChecker.GOOGLE_ARGS_REGEX.match(line)
             if match:
                 docstring_args.add(match.group(1))
+        yield from ConventionChecker._check_missing_args(docstring_args, definition)
+
+
+    @staticmethod
+    def _check_missing_args(docstring_args, definition):
+        """D417: Yield error for missing arguments in docstring.
+
+        Given a list of arguments found in the docstring and the
+        callable definition, it checks if all the arguments of the
+        callable are present in the docstring, else it yields a
+        D417 with a list of missing arguments.
+
+        """
         function_args = get_function_args(definition.source)
         # If the method isn't static, then we skip the first
         # positional argument as it is `cls` or `self`

src/pydocstyle/violations.py

@@ -252,8 +252,8 @@ def to_rst(cls) -> str:
                                  'mark, or exclamation point', 'not {0!r}')
 D416 = D4xx.create_error('D416', 'Section name should end with a colon',
                          '{0!r}, not {1!r}')
-D417 = D4xx.create_error('D417', 'Missing arguments in the docstring',
-                         'argument(s) {0!r} missing in {1!r} docstring')
+D417 = D4xx.create_error('D417', 'Missing argument descriptions in the docstring',
+                         'argument(s) {0} are missing descriptions in {1!r} docstring')
 
 class AttrDict(dict):
     def __getattr__(self, item: str) -> Any:

src/tests/test_cases/sections.py

@@ -275,10 +275,10 @@ def missing_colon_google_style_section():  # noqa: D406, D407
 
 
 @expect(_D213)
-@expect("D417: Missing arguments in the docstring "
-        "(argument(s) 'y' missing in "
-        "'test_missing_args' docstring)")
-def test_missing_args(x=1, y=2):  # noqa: D406, D407
+@expect("D417: Missing argument descriptions in the docstring "
+        "(argument(s) y are missing descriptions in "
+        "'test_missing_google_args' docstring)")
+def test_missing_google_args(x=1, y=2):  # noqa: D406, D407
     """Toggle the gizmo.
 
     Args:
@@ -287,7 +287,7 @@ def test_missing_args(x=1, y=2):  # noqa: D406, D407
     """
 
 
-class Test:  # noqa: D203
+class TestGoogle:  # noqa: D203
     """Test class."""
 
     def test_method(self, test, another_test):  # noqa: D213, D407
@@ -299,8 +299,8 @@ def test_method(self, test, another_test):  # noqa: D213, D407
 
         """
 
-    @expect("D417: Missing arguments in the docstring "
-            "(argument(s) 'test, y, z' missing in "
+    @expect("D417: Missing argument descriptions in the docstring "
+            "(argument(s) test, y, z are missing descriptions in "
             "'test_missing_args' docstring)", arg_count=4)
     def test_missing_args(self, test, x, y, z=3):  # noqa: D213, D407
         """Test a valid args section.
@@ -311,20 +311,21 @@ def test_missing_args(self, test, x, y, z=3):  # noqa: D213, D407
         """
 
     @classmethod
-    @expect("D417: Missing arguments in the docstring "
-            "(argument(s) 'test, y, z' missing in "
+    @expect("D417: Missing argument descriptions in the docstring "
+            "(argument(s) test, y, z are missing descriptions in "
             "'test_missing_args_class_method' docstring)", arg_count=4)
     def test_missing_args_class_method(cls, test, x, y, z=3):  # noqa: D213, D407
         """Test a valid args section.
 
         Args:
-            x: Another parameter.
+            x: Another parameter. The parameter below is missing description.
+            y:
 
         """
 
     @staticmethod
-    @expect("D417: Missing arguments in the docstring "
-            "(argument(s) 'a, y, z' missing in "
+    @expect("D417: Missing argument descriptions in the docstring "
+            "(argument(s) a, y, z are missing descriptions in "
             "'test_missing_args_static_method' docstring)", arg_count=3)
     def test_missing_args_static_method(a, x, y, z=3):  # noqa: D213, D407
         """Test a valid args section.
@@ -333,3 +334,83 @@ def test_missing_args_static_method(a, x, y, z=3):  # noqa: D213, D407
             x: Another parameter.
 
         """
+
+
+@expect(_D213)
+@expect("D417: Missing argument descriptions in the docstring "
+        "(argument(s) y are missing descriptions in "
+        "'test_missing_numpy_args' docstring)")
+def test_missing_numpy_args(x=1, y=2):  # noqa: D406, D407
+    """Toggle the gizmo.
+
+    Parameters
+    ----------
+    x : int
+        The greatest integer.
+
+    """
+
+
+class TestNumpy:  # noqa: D203
+    """Test class."""
+
+    def test_method(self, test, another_test, x=1, y=2):  # noqa: D213, D407
+        """Test a valid args section.
+
+        Parameters
+        ----------
+        test, another_test
+            Some parameters without type.
+        x, y : int
+            Some integer parameters.
+
+        """
+
+    @expect("D417: Missing argument descriptions in the docstring "
+            "(argument(s) test, y, z are missing descriptions in "
+            "'test_missing_args' docstring)", arg_count=4)
+    def test_missing_args(self, test, x, y, z=3, t=1):  # noqa: D213, D407
+        """Test a valid args section.
+
+        Parameters
+        ----------
+        x, t : int
+            Some parameters.
+
+
+        """
+
+    @classmethod
+    @expect("D417: Missing argument descriptions in the docstring "
+            "(argument(s) test, y, z are missing descriptions in "
+            "'test_missing_args_class_method' docstring)", arg_count=4)
+    def test_missing_args_class_method(cls, test, x, y, z=3):  # noqa: D213, D407
+        """Test a valid args section.
+
+        Parameters
+        ----------
+        z
+        x
+            Another parameter. The parameters y, test below are
+            missing descriptions. The parameter z above is also missing
+            a description.
+        y
+        test
+
+        """
+
+    @staticmethod
+    @expect("D417: Missing argument descriptions in the docstring "
+            "(argument(s) a, z are missing descriptions in "
+            "'test_missing_args_static_method' docstring)", arg_count=3)
+    def test_missing_args_static_method(a, x, y, z=3, t=1):  # noqa: D213, D407
+        """Test a valid args section.
+
+        Parameters
+        ----------
+        x, y
+            Another parameter.
+        t : int
+            Yet another parameter.
+
+        """