Tweak docs on review

changelog/9288.breaking.rst

@@ -1 +1,7 @@
-Set :func:`warns` to re-emit unmatched warnings when the context closes
+:func:`pytest.warns <warns>` now re-emits unmatched warnings when the context
+closes -- previously it would consume all warnings, hiding those that were not
+matched by the function.
+
+While this is a new feature, we decided to announce this as a breaking change
+because many test suites are configured to error-out on warnings, and will
+therefore fail on the newly-re-emitted warnings.

src/_pytest/recwarn.py

@@ -117,10 +117,10 @@ def warns(  # noqa: F811
     warning of that class or classes.
 
     This helper produces a list of :class:`warnings.WarningMessage` objects, one for
-    each warning raised (regardless of whether it is an ``expected_warning`` or not).
+    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, which will capture all the raised
-    warnings inside it::
+    This function can be used as a context manager::
 
         >>> import pytest
         >>> with pytest.warns(RuntimeWarning):
@@ -150,10 +150,6 @@ def warns(  # noqa: F811
     This could be achieved in the same way as with exceptions, see
     :ref:`parametrizing_conditional_raising` for an example.
 
-    .. note::
-        Unlike the stdlib :func:`warnings.catch_warnings` context manager,
-        unmatched warnings will be re-emitted when the context closes.
-
     """
     __tracebackhide__ = True
     if not args:
@@ -328,7 +324,7 @@ def found_str():
                 if not self.matches(w):
                     warnings.warn_explicit(
                         str(w.message),
-                        w.message.__class__,  # type: ignore
+                        w.message.__class__,  # type: ignore[arg-type]
                         w.filename,
                         w.lineno,
                         module=w.__module__,