Improve warnings docs (#6366)

Improve warnings docs

doc/en/warnings.rst

@@ -198,7 +198,7 @@ the regular expression ``".*U.*mode is deprecated"``.
 Ensuring code triggers a deprecation warning
 --------------------------------------------
 
-You can also call a global helper for checking
+You can also use :func:`pytest.deprecated_call` for checking
 that a certain function call triggers a ``DeprecationWarning`` or
 ``PendingDeprecationWarning``:
 
@@ -207,13 +207,18 @@ that a certain function call triggers a ``DeprecationWarning`` or
     import pytest
 
 
-    def test_global():
+    def test_myfunction_deprecated():
-        pytest.deprecated_call(myfunction, 17)
+        with pytest.deprecated_call():
+            myfunction(17)
+
+This test will fail if ``myfunction`` does not issue a deprecation warning
+when called with a ``17`` argument.
 
 By default, ``DeprecationWarning`` and ``PendingDeprecationWarning`` will not be
-caught when using ``pytest.warns`` or ``recwarn`` because default Python warnings filters hide
+caught when using :func:`pytest.warns` or :ref:`recwarn <recwarn>` because
-them. If you wish to record them in your own code, use the
+the default Python warnings filters hide
-command ``warnings.simplefilter('always')``:
+them. If you wish to record them in your own code, use
+``warnings.simplefilter('always')``:
 
 .. code-block:: python
 
@@ -223,19 +228,13 @@ command ``warnings.simplefilter('always')``:
 
     def test_deprecation(recwarn):
         warnings.simplefilter("always")
-        warnings.warn("deprecated", DeprecationWarning)
+        myfunction(17)
         assert len(recwarn) == 1
         assert recwarn.pop(DeprecationWarning)
 
-You can also use it as a contextmanager:
-
-.. code-block:: python
-
-    def test_global():
-        with pytest.deprecated_call():
-            myobject.deprecated_method()
-
 
+The :ref:`recwarn <recwarn>` fixture automatically ensures to reset the warnings
+filter at the end of the test, so no global state is leaked.
 
 .. _`asserting warnings`: