Add support for D417 missing argument docstrings

pydocstyle now supports checking for missing function arguments
from docstrings.

Author: sambhav

src/pydocstyle/checker.py

@@ -4,7 +4,7 @@
 import string
 import sys
 import tokenize as tk
-from itertools import takewhile
+from itertools import takewhile, chain
 from re import compile as re
 from collections import namedtuple
 
@@ -668,6 +668,26 @@ def _check_numpy_section(cls, docstring, definition, context):
         if suffix:
             yield violations.D406(capitalized_section, context.line.strip())
 
+    @staticmethod
+    def _check_args_section(docstring, definition, context):
+        """D417: `Args` section checks.
+
+        Check for a valid `Args` or `Argument` section. Checks that:
+            * The section documents all function arguments (D417)
+                except `self` or `cls` if it is a method.
+
+        """
+        if definition.kind == 'function':
+            function_pos_args = get_function_args(definition.source)
+            docstring_args = set()
+            for line in context.following_lines:
+                match = ConventionChecker.GOOGLE_ARGS_REGEX.match(line)
+                if match:
+                    docstring_args.add(match.group(1))
+            missing_args = function_pos_args - docstring_args
+            if missing_args:
+                yield violations.D417(", ".join(missing_args), definition.name)
+
     @classmethod
     def _check_google_section(cls, docstring, definition, context):
         """D416: Google-style section name checks.
@@ -690,6 +710,9 @@ def _check_google_section(cls, docstring, definition, context):
         if suffix != ":":
             yield violations.D416(capitalized_section + ":", context.line.strip())
 
+        if capitalized_section in ("Args", "Arguments"):
+            yield from cls._check_args_section(docstring, definition, context)
+
 
     @staticmethod
     def _get_section_contexts(lines, valid_section_names):
@@ -804,7 +827,6 @@ def check_docstring_sections(self, definition, docstring):
         lines = docstring.split("\n")
         if len(lines) < 2:
             return
-
         yield from self._check_numpy_sections(lines, definition, docstring)
         yield from self._check_google_sections(lines, definition, docstring)
 
@@ -887,3 +909,11 @@ def get_leading_words(line):
     result = re("[\w ]+").match(line.strip())
     if result is not None:
         return result.group()
+
+
+def get_function_args(function_string):
+    """Return the function arguments given the source-code string."""
+    function_arg_node = ast.parse(function_string).body[0].args
+    arg_nodes = function_arg_node.args
+    kwonly_arg_nodes = function_arg_node.kwonlyargs
+    return set(arg_node.arg for arg_node in chain(arg_nodes, kwonly_arg_nodes))

src/pydocstyle/violations.py

@@ -251,6 +251,8 @@ def to_rst(cls) -> str:
                                  'mark, or exclamation point', 'not {0!r}')
 D416 = D4xx.create_error('D416', 'Section name should end with a semicolon',
                          '{0!r}, not {1!r}')
+D417 = D4xx.create_error('D417', 'Missing arguments in the function docstring',
+                         'argument(s) {0!r} missing in function {1!r} docstring')
 
 class AttrDict(dict):
     def __getattr__(self, item: str) -> Any:
@@ -263,9 +265,9 @@ def __getattr__(self, item: str) -> Any:
 conventions = AttrDict({
     'pep257': all_errors - {'D203', 'D212', 'D213', 'D214', 'D215', 'D404',
                             'D405', 'D406', 'D407', 'D408', 'D409', 'D410',
-                            'D411', 'D415', 'D416'},
+                            'D411', 'D415', 'D416', 'D417'},
     'numpy': all_errors - {'D107', 'D203', 'D212', 'D213', 'D402', 'D413',
-                           'D415', 'D416'},
+                           'D415', 'D416', 'D417'},
     'google': all_errors - {'D203', 'D204', 'D213', 'D215', 'D400', 'D401',
                             'D404', 'D406', 'D407', 'D408', 'D409'}
 })

src/tests/test_cases/sections.py

@@ -272,3 +272,16 @@ def missing_colon_google_style_section():  # noqa: D406, D407
         note: A random string.
 
     """
+
+
+@expect(_D213)
+@expect("D417: Missing arguments in the function docstring "
+        "(argument(s) 'y' missing in function "
+        "'test_missing_args' docstring)")
+def test_missing_args(x=1, y=2):  # noqa: D407, D407
+    """Toggle the gizmo.
+
+    Args:
+        x (int): The greatest integer.
+
+    """

src/tests/test_integration.py

@@ -664,6 +664,7 @@ def __init__(self):
     assert 'D412' in out
     assert 'D413' in out
     assert 'D414' in out
+    assert 'D417' in out
 
 
 def test_config_file_inheritance(env):