From 84e59af8c829de659efb339d5a9c7cec98eee719 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Sun, 5 May 2024 19:53:16 -0300
Subject: [PATCH] Document exceptions raised by exit, skip, xfail, fail, and
 importorskip (#12285)

As commented on: https://github.com/pytest-dev/pytest/issues/7469#issuecomment-2094104215
---
 doc/en/reference/reference.rst | 19 ++++++++++++++++++-
 src/_pytest/outcomes.py        | 15 +++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst
index 39317497e..e46478da0 100644
--- a/doc/en/reference/reference.rst
+++ b/doc/en/reference/reference.rst
@@ -59,11 +59,19 @@ pytest.fail
 
 .. autofunction:: pytest.fail(reason, [pytrace=True, msg=None])
 
+.. class:: pytest.fail.Exception
+
+    The exception raised by :func:`pytest.fail`.
+
 pytest.skip
 ~~~~~~~~~~~
 
 .. autofunction:: pytest.skip(reason, [allow_module_level=False, msg=None])
 
+.. class:: pytest.skip.Exception
+
+    The exception raised by :func:`pytest.skip`.
+
 .. _`pytest.importorskip ref`:
 
 pytest.importorskip
@@ -76,11 +84,19 @@ pytest.xfail
 
 .. autofunction:: pytest.xfail
 
+.. class:: pytest.xfail.Exception
+
+    The exception raised by :func:`pytest.xfail`.
+
 pytest.exit
 ~~~~~~~~~~~
 
 .. autofunction:: pytest.exit(reason, [returncode=None, msg=None])
 
+.. class:: pytest.exit.Exception
+
+    The exception raised by :func:`pytest.exit`.
+
 pytest.main
 ~~~~~~~~~~~
 
@@ -246,9 +262,10 @@ Marks a test function as *expected to fail*.
         to specify ``reason`` (see :ref:`condition string <string conditions>`).
     :keyword str reason:
         Reason why the test function is marked as xfail.
-    :keyword Type[Exception] raises:
+    :keyword raises:
         Exception class (or tuple of classes) expected to be raised by the test function; other exceptions will fail the test.
         Note that subclasses of the classes passed will also result in a match (similar to how the ``except`` statement works).
+    :type raises: Type[:py:exc:`Exception`]
 
     :keyword bool run:
         Whether the test function should actually be executed. If ``False``, the function will always xfail and will
diff --git a/src/_pytest/outcomes.py b/src/_pytest/outcomes.py
index 76d94accd..f953dabe0 100644
--- a/src/_pytest/outcomes.py
+++ b/src/_pytest/outcomes.py
@@ -114,6 +114,9 @@ def exit(
 
     :param returncode:
         Return code to be used when exiting pytest. None means the same as ``0`` (no error), same as :func:`sys.exit`.
+
+    :raises pytest.exit.Exception:
+        The exception that is raised.
     """
     __tracebackhide__ = True
     raise Exit(reason, returncode)
@@ -142,6 +145,9 @@ def skip(
 
         Defaults to False.
 
+    :raises pytest.skip.Exception:
+        The exception that is raised.
+
     .. note::
         It is better to use the :ref:`pytest.mark.skipif ref` marker when
         possible to declare a test to be skipped under certain conditions
@@ -163,6 +169,9 @@ def fail(reason: str = "", pytrace: bool = True) -> NoReturn:
     :param pytrace:
         If False, msg represents the full failure information and no
         python traceback will be reported.
+
+    :raises pytest.fail.Exception:
+        The exception that is raised.
     """
     __tracebackhide__ = True
     raise Failed(msg=reason, pytrace=pytrace)
@@ -188,6 +197,9 @@ def xfail(reason: str = "") -> NoReturn:
         It is better to use the :ref:`pytest.mark.xfail ref` marker when
         possible to declare a test to be xfailed under certain conditions
         like known bugs or missing features.
+
+    :raises pytest.xfail.Exception:
+        The exception that is raised.
     """
     __tracebackhide__ = True
     raise XFailed(reason)
@@ -227,6 +239,9 @@ def importorskip(
     :returns:
         The imported module. This should be assigned to its canonical name.
 
+    :raises pytest.skip.Exception:
+        If the module cannot be imported.
+
     Example::
 
         docutils = pytest.importorskip("docutils")