From 1827d8d5f9164da3cf8a7f0a22ea6c36814fdfd4 Mon Sep 17 00:00:00 2001
From: Ran Benita <ran@unusedvar.com>
Date: Sat, 12 Aug 2023 18:02:13 +0300
Subject: [PATCH] doc: fix a few `pytest.mark.xfail` nits

Refs #9027, #10094.
---
 doc/en/reference/reference.rst | 8 +++++---
 src/_pytest/mark/structures.py | 4 +++-
 src/_pytest/outcomes.py        | 3 +++
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst
index a6d7cfdd4..5a2458bcb 100644
--- a/doc/en/reference/reference.rst
+++ b/doc/en/reference/reference.rst
@@ -237,7 +237,7 @@ pytest.mark.xfail
 
 Marks a test function as *expected to fail*.
 
-.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=False)
+.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=xfail_strict)
 
     :type condition: bool or str
     :param condition:
@@ -249,10 +249,10 @@ Marks a test function as *expected to fail*.
     :keyword Type[Exception] raises:
         Exception subclass (or tuple of subclasses) expected to be raised by the test function; other exceptions will fail the test.
     :keyword bool run:
-        If the test function should actually be executed. If ``False``, the function will always xfail and will
+        Whether the test function should actually be executed. If ``False``, the function will always xfail and will
         not be executed (useful if a function is segfaulting).
     :keyword bool strict:
-        * If ``False`` (the default) the function will be shown in the terminal output as ``xfailed`` if it fails
+        * If ``False`` the function will be shown in the terminal output as ``xfailed`` if it fails
           and as ``xpass`` if it passes. In both cases this will not cause the test suite to fail as a whole. This
           is particularly useful to mark *flaky* tests (tests that fail at random) to be tackled later.
         * If ``True``, the function will be shown in the terminal output as ``xfailed`` if it fails, but if it
@@ -260,6 +260,8 @@ Marks a test function as *expected to fail*.
           that are always failing and there should be a clear indication if they unexpectedly start to pass (for example
           a new release of a library fixes a known bug).
 
+        Defaults to :confval:`xfail_strict`, which is ``False`` by default.
+
 
 Custom marks
 ~~~~~~~~~~~~
diff --git a/src/_pytest/mark/structures.py b/src/_pytest/mark/structures.py
index d6e426567..bbde68644 100644
--- a/src/_pytest/mark/structures.py
+++ b/src/_pytest/mark/structures.py
@@ -461,7 +461,9 @@ if TYPE_CHECKING:
             *conditions: Union[str, bool],
             reason: str = ...,
             run: bool = ...,
-            raises: Union[Type[BaseException], Tuple[Type[BaseException], ...]] = ...,
+            raises: Union[
+                None, Type[BaseException], Tuple[Type[BaseException], ...]
+            ] = ...,
             strict: bool = ...,
         ) -> MarkDecorator:
             ...
diff --git a/src/_pytest/outcomes.py b/src/_pytest/outcomes.py
index 7dab4499b..a8984c5b9 100644
--- a/src/_pytest/outcomes.py
+++ b/src/_pytest/outcomes.py
@@ -233,6 +233,9 @@ def xfail(reason: str = "") -> NoReturn:
 
     This function should be called only during testing (setup, call or teardown).
 
+    No other code is executed after using ``xfail()`` (it is implemented
+    internally by raising an exception).
+
     :param reason:
         The message to show the user as reason for the xfail.