[7.0.x] Add docs on pytest.warns(None) deprecation

doc/en/deprecations.rst

@@ -221,11 +221,11 @@ Using ``pytest.warns(None)``
 
 .. deprecated:: 7.0
 
-:func:`pytest.warns(None) <pytest.warns>` is now deprecated because many people used
-it to mean "this code does not emit warnings", but it actually had the effect of
-checking that the code emits at least one warning of any type - like ``pytest.warns()``
+:func:`pytest.warns(None) <pytest.warns>` is now deprecated because it was frequently misused.
+Its correct usage was checking that the code emits at least one warning of any type - like ``pytest.warns()``
 or ``pytest.warns(Warning)``.
 
+See :ref:`warns use cases` for examples.
 
 The ``--strict`` command-line option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

@@ -351,6 +351,35 @@ warnings, or index into it to get a particular recorded warning.
 
 Full API: :class:`~_pytest.recwarn.WarningsRecorder`.
 
+.. _`warns use cases`:
+
+Additional use cases of warnings in tests
+-----------------------------------------
+
+Here are some use cases involving warnings that often come up in tests, and suggestions on how to deal with them:
+
+- To ensure that **any** warning is emitted, use:
+
+.. code-block:: python
+
+    with pytest.warns():
+        pass
+
+-  To ensure that **no** warnings are emitted, use:
+
+.. code-block:: python
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+
+- To suppress warnings, use:
+
+.. code-block:: python
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+
+
 .. _custom_failure_messages:
 
 Custom failure messages