Merge pull request #7979 from nicoddemus/metafunc-ref

Add FunctionDefinition to the reference docs

Author: nicoddemus

doc/en/reference.rst

@@ -840,6 +840,13 @@ Function
     :members:
     :show-inheritance:
 
+FunctionDefinition
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: _pytest.python.FunctionDefinition()
+    :members:
+    :show-inheritance:
+
 Item
 ~~~~
 

src/_pytest/python.py

@@ -960,6 +960,7 @@ def __init__(
         cls=None,
         module=None,
     ) -> None:
+        #: Access to the underlying :class:`_pytest.python.FunctionDefinition`.
         self.definition = definition
 
         #: Access to the :class:`_pytest.config.Config` object for the test session.
@@ -1677,10 +1678,12 @@ def repr_failure(  # type: ignore[override]
 
 
 class FunctionDefinition(Function):
-    """Internal hack until we get actual definition nodes instead of the
-    crappy metafunc hack."""
+    """
+    This class is a step gap solution until we evolve to have actual function definition nodes
+    and manage to get rid of ``metafunc``.
+    """
 
     def runtest(self) -> None:
-        raise RuntimeError("function definitions are not supposed to be used")
+        raise RuntimeError("function definitions are not supposed to be run as tests")
 
     setup = runtest