recwarn: type annotate pytest.deprecated_call

Also improve its documentation.

src/_pytest/recwarn.py

@@ -38,9 +38,26 @@ def recwarn() -> Generator["WarningsRecorder", None, None]:
         yield wrec
 
 
-def deprecated_call(func=None, *args, **kwargs):
+@overload
-    """context manager that can be used to ensure a block of code triggers a
+def deprecated_call(
-    ``DeprecationWarning`` or ``PendingDeprecationWarning``::
+    *, match: Optional[Union[str, "Pattern"]] = ...
+) -> "WarningsRecorder":
+    raise NotImplementedError()
+
+
+@overload  # noqa: F811
+def deprecated_call(  # noqa: F811
+    func: Callable[..., T], *args: Any, **kwargs: Any
+) -> T:
+    raise NotImplementedError()
+
+
+def deprecated_call(  # noqa: F811
+    func: Optional[Callable] = None, *args: Any, **kwargs: Any
+) -> Union["WarningsRecorder", Any]:
+    """Assert that code produces a ``DeprecationWarning`` or ``PendingDeprecationWarning``.
+
+    This function can be used as a context manager::
 
         >>> import warnings
         >>> def api_call_v2():
@@ -50,9 +67,15 @@ def deprecated_call(func=None, *args, **kwargs):
         >>> with deprecated_call():
         ...    assert api_call_v2() == 200
 
-    ``deprecated_call`` can also be used by passing a function and ``*args`` and ``*kwargs``,
+    It can also be used by passing a function and ``*args`` and ``**kwargs``,
-    in which case it will ensure calling ``func(*args, **kwargs)`` produces one of the warnings
+    in which case it will ensure calling ``func(*args, **kwargs)`` produces one of
-    types above.
+    the warnings types above. The return value is the return value of the function.
+
+    In the context manager form you may use the keyword argument ``match`` to assert
+    that the warning matches a text or regex.
+
+    The context manager produces a list of :class:`warnings.WarningMessage` objects,
+    one for each warning raised.
     """
     __tracebackhide__ = True
     if func is not None: