refactor: Improve "unknown parameter" messages

Issue mkdocstrings/mkdocstrings#423: mkdocstrings/mkdocstrings#423

src/griffe/docstrings/google.py

@@ -207,13 +207,15 @@ def _read_parameters( # noqa: WPS231
  _warn(docstring, line_number, f"No type or annotation for parameter '{name}'")
 
  if warn_unknown_params:
- with suppress(AttributeError): # for parameters sections in non-function docstrings
- if name not in docstring.parent.parameters: # type: ignore[union-attr]
- _warn(
- docstring,
- line_number,
- f"Parameter '{name}' does not appear in the parent signature",
- )
+ with suppress(AttributeError): # for parameters sections in objects without parameters
+ params = docstring.parent.parameters # type: ignore[union-attr]
+ if name not in params:
+ message = f"Parameter '{name}' does not appear in the function signature"
+ for starred_name in (f"*{name}", f"**{name}"):
+ if starred_name in params:
+ message += f". Did you mean '{starred_name}'?"
+ break
+ _warn(docstring, line_number, message)
 
  parameters.append(DocstringParameter(name=name, value=default, annotation=annotation, description=description))
 

src/griffe/docstrings/numpy.py

@@ -261,14 +261,17 @@ def _read_parameters( # noqa: WPS231
  default = docstring.parent.parameters[name].default # type: ignore[union-attr]
  break
 
- if warn_unknown_params and docstring.parent is not None:
- for name in names: # noqa: WPS440
- if name not in docstring.parent.parameters: # type: ignore[attr-defined]
- _warn(
- docstring,
- new_offset,
- f"Parameter '{name}' does not appear in the parent signature",
- )
+ if warn_unknown_params:
+ with suppress(AttributeError): # for parameters sections in objects without parameters
+ params = docstring.parent.parameters # type: ignore[union-attr]
+ for name in names: # noqa: WPS440
+ if name not in params:
+ message = f"Parameter '{name}' does not appear in the function signature"
+ for starred_name in (f"*{name}", f"**{name}"):
+ if starred_name in params:
+ message += f". Did you mean '{starred_name}'?"
+ break
+ _warn(docstring, new_offset, message)
 
  for name in names: # noqa: WPS440
  parameters.append(DocstringParameter(name, value=default, annotation=annotation, description=description))

tests/test_docstrings/test_google.py

@@ -725,7 +725,7 @@ def test_warn_about_unknown_parameters(parse_google):
  ),
  )
  assert len(warnings) == 1
- assert "'x' does not appear in the parent signature" in warnings[0]
+ assert "'x' does not appear in the function signature" in warnings[0]
 
 
 def test_never_warn_about_unknown_other_parameters(parse_google):
@@ -779,15 +779,8 @@ def test_class_uses_init_parameters(parse_google):
  Parameters:
  x: X value.
  """
-
  parent = Class("c")
- parent["__init__"] = Function(
- "__init__",
- parameters=Parameters(
- Parameter("x", annotation="int"),
- ),
- )
-
+ parent["__init__"] = Function("__init__", parameters=Parameters(Parameter("x", annotation="int")))
  sections, warnings = parse_google(docstring, parent=parent)
  assert not warnings
  argx = sections[0].value[0]

tests/test_docstrings/test_numpy.py

@@ -555,7 +555,7 @@ def test_warn_about_unknown_parameters(parse_numpy):
  ),
  )
  assert len(warnings) == 1
- assert "'x' does not appear in the parent signature" in warnings[0]
+ assert "'x' does not appear in the function signature" in warnings[0]
 
 
 def test_never_warn_about_unknown_other_parameters(parse_numpy):
@@ -586,6 +586,48 @@ def test_never_warn_about_unknown_other_parameters(parse_numpy):
  assert not warnings
 
 
+def test_unknown_params_scan_doesnt_crash_without_parameters(parse_numpy):
+ """Assert we don't crash when parsing parameters sections and parent object does not have parameters.
+
+ Parameters:
+ parse_numpy: Fixture parser.
+ """
+ docstring = """
+ Parameters
+ ----------
+ this : str
+ This.
+ that : str
+ That.
+ """
+
+ _, warnings = parse_numpy(docstring, parent=Module("mod"))
+ assert not warnings
+
+
+def test_class_uses_init_parameters(parse_numpy):
+ """Assert we use the `__init__` parameters when parsing classes' parameters sections.
+
+ Parameters:
+ parse_numpy: Fixture parser.
+ """
+ docstring = """
+ Parameters
+ ----------
+ x :
+ X value.
+ """
+
+ parent = Class("c")
+ parent["__init__"] = Function("__init__", parameters=Parameters(Parameter("x", annotation="int")))
+ sections, warnings = parse_numpy(docstring, parent=parent)
+ assert not warnings
+ argx = sections[0].value[0]
+ assert argx.name == "x"
+ assert argx.annotation == "int"
+ assert argx.description == "X value."
+
+
 # =============================================================================================
 # Yields sections
 @pytest.mark.parametrize(