doc: undocument legacy forms of raises, warns, deprecated_call

We don't intend to deprecate the legacy forms, but there is no reason to
use them anymore, and they add complexity/confusion, so let's just
mostly pretend they don't exist in the docs.

Author: jakkdl

doc/en/how-to/assert.rst

@@ -322,13 +322,9 @@ will then execute the function with those arguments and assert that the given ex
 
     pytest.raises(ValueError, func, x=-1)
 
-The reporter will provide you with helpful output in case of failures such as *no
-exception* or *wrong exception*.
-
 This form was the original :func:`pytest.raises` API, developed before the ``with`` statement was
 added to the Python language. Nowadays, this form is rarely used, with the context-manager form (using ``with``)
 being considered more readable.
-Nonetheless, this form is fully supported and not deprecated in any way.
 
 xfail mark and pytest.raises
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/en/how-to/capture-warnings.rst

@@ -371,13 +371,6 @@ Some examples:
     ...     warnings.warn("issue with foo() func")
     ...
 
-You can also call :func:`pytest.warns` on a function or code string:
-
-.. code-block:: python
-
-    pytest.warns(expected_warning, func, *args, **kwargs)
-    pytest.warns(expected_warning, "func(*args, **kwargs)")
-
 The function also returns a list of all raised warnings (as
 ``warnings.WarningMessage`` objects), which you can query for
 additional information:

src/_pytest/raises.py

@@ -237,25 +237,6 @@ def raises(
 
         :ref:`assertraises` for more examples and detailed discussion.
 
-    **Legacy form**
-
-    It is possible to specify a callable by passing a to-be-called lambda::
-
-        >>> raises(ZeroDivisionError, lambda: 1/0)
-        <ExceptionInfo ...>
-
-    or you can specify an arbitrary callable with arguments::
-
-        >>> def f(x): return 1/x
-        ...
-        >>> raises(ZeroDivisionError, f, 0)
-        <ExceptionInfo ...>
-        >>> raises(ZeroDivisionError, f, x=0)
-        <ExceptionInfo ...>
-
-    The form above is fully supported but discouraged for new code because the
-    context manager form is regarded as more readable and less error-prone.
-
     .. note::
         Similar to caught exception objects in Python, explicitly clearing
         local references to returned ``ExceptionInfo`` objects can

src/_pytest/recwarn.py

@@ -67,16 +67,15 @@ def deprecated_call(
         >>> import pytest
         >>> with pytest.deprecated_call():
         ...    assert api_call_v2() == 200
+        >>> with pytest.deprecated_call(match="^use v3 of this api$") as warning_messages:
+        ...    assert api_call_v2() == 200
 
-    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 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
+    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.
+    The return value is a list of :class:`warnings.WarningMessage` objects,
+    one for each warning emitted
+    (regardless of whether it is an ``expected_warning`` or not).
     """
     __tracebackhide__ = True
     if func is not None:
@@ -119,13 +118,13 @@ def warns(
     each warning emitted (regardless of whether it is an ``expected_warning`` or not).
     Since pytest 8.0, unmatched warnings are also re-emitted when the context closes.
 
-    This function can be used as a context manager::
+    This function should be used as a context manager::
 
         >>> import pytest
         >>> with pytest.warns(RuntimeWarning):
         ...    warnings.warn("my warning", RuntimeWarning)
 
-    In the context manager form you may use the keyword argument ``match`` to assert
+    The ``match`` keyword argument can be used to assert
     that the warning matches a text or regex::
 
         >>> with pytest.warns(UserWarning, match='must be 0 or None'):