feat: warn if docstring has extra parameters

src/griffe/dataclasses.py

@@ -247,6 +247,9 @@ def __len__(self):
     def __iter__(self):
         return iter(self._parameters_list)
 
+    def __contains__(self, item):
+        return item in self._parameters_dict
+
     def add(self, parameter: Parameter) -> None:
         """Add a parameter to the container.
 

src/griffe/docstrings/google.py

@@ -161,7 +161,9 @@ def _read_block(docstring: Docstring, offset: int) -> tuple[str, int]:
     return "\n".join(block).rstrip("\n"), new_offset - 1
 
 
-def _read_parameters(docstring: Docstring, offset: int) -> tuple[list[DocstringParameter], int]:  # noqa: WPS231
+def _read_parameters(
+    docstring: Docstring, offset: int, warn_unknown_params: bool = True
+) -> tuple[list[DocstringParameter], int]:  # noqa: WPS231
     parameters = []
     annotation: str | Name | Expression | None
 
@@ -202,6 +204,14 @@ def _read_parameters(docstring: Docstring, offset: int) -> tuple[list[DocstringP
         if annotation is None:
             _warn(docstring, line_number, f"No type or annotation for parameter '{name}'")
 
+        if warn_unknown_params and docstring.parent is not None:
+            if name not in docstring.parent.parameters:
+                _warn(
+                    docstring,
+                    line_number,
+                    f'The docstring for {docstring.parent} contains "{name}" as a parameter, but "{name}" is not an argument.',
+                )
+
         parameters.append(DocstringParameter(name=name, value=default, annotation=annotation, description=description))
 
     return parameters, new_offset

tests/test_docstrings/test_google.py

@@ -702,22 +702,34 @@ def test_parameter_line_without_colon_keyword_only(parse_google):
     assert "Empty" in warnings[1]
 
 
-# TODO: possible feature
-# def test_extra_parameter(parse_google):
-#     """Warn on extra parameter in docstring.
-#
-#     Parameters:
-#         parse_google: Fixture parser.
-#     """
-#     docstring = """
-#         Parameters:
-#             x: Integer.
-#             y: Integer.
-#     """
+def test_extra_parameter(parse_google):
+    """Warn on extra parameter in docstring.
 
-#     sections, warnings = parse_google(docstring)
-#     assert len(sections) == 1
-#     assert len(warnings) == 2
+    Parameters:
+        parse_google: Fixture parser.
+    """
+    docstring = """
+        Parameters:
+            x: Integer.
+            y: Integer.
+    """
+
+    sections, warnings = parse_google(
+        docstring,
+        parent=Function(
+            "func",
+            parameters=Parameters(
+                Parameter("a"),
+                Parameter("y"),
+            ),
+        ),
+    )
+    assert len(sections) == 1
+    assert len(warnings) == 3
+    assert (
+        'The docstring for <Function(\'func\', None, None)> contains "x" as a parameter, but "x" is not an argument.'
+        in warnings
+    )
 
 
 # TODO: possible feature