Improve docs and reference

changelog/3457.feature.rst

@@ -1,2 +1,4 @@
-Adds ``pytest_assertion_pass`` hook, called with assertion context information
-(original asssertion statement and pytest explanation) whenever an assertion passes.
+New `pytest_assertion_pass <https://docs.pytest.org/en/latest/reference.html#_pytest.hookspec.pytest_assertion_pass>`__
+hook, called with context information when an assertion *passes*.
+
+This hook is still **experimental** so use it with caution.

doc/en/reference.rst

@@ -665,15 +665,14 @@ Session related reporting hooks:
 .. autofunction:: pytest_fixture_post_finalizer
 .. autofunction:: pytest_warning_captured
 
-And here is the central hook for reporting about
-test execution:
+Central hook for reporting about test execution:
 
 .. autofunction:: pytest_runtest_logreport
 
-You can also use this hook to customize assertion representation for some
-types:
+Assertion related hooks:
 
 .. autofunction:: pytest_assertrepr_compare
+.. autofunction:: pytest_assertion_pass
 
 
 Debugging/Interaction hooks

src/_pytest/hookspec.py

@@ -486,13 +486,27 @@ def pytest_assertrepr_compare(config, op, left, right):
 
 
 def pytest_assertion_pass(item, lineno, orig, expl):
-    """Process explanation when assertions are valid.
+    """
+    **(Experimental)**
+
+    Hook called whenever an assertion *passes*.
 
     Use this hook to do some processing after a passing assertion.
     The original assertion information is available in the `orig` string
     and the pytest introspected assertion information is available in the
     `expl` string.
 
+    This hook must be explicitly enabled by the ``enable_assertion_pass_hook``
+    ini-file option:
+
+    .. code-block:: ini
+
+        [pytest]
+        enable_assertion_pass_hook=true
+
+    You need to **clean the .pyc** files in your project directory and interpreter libraries
+    when enabling this option, as assertions will require to be re-written.
+
     :param _pytest.nodes.Item item: pytest item object of current test
     :param int lineno: line number of the assert statement
     :param string orig: string with original assertion
@@ -500,12 +514,9 @@ def pytest_assertion_pass(item, lineno, orig, expl):
 
     .. note::
 
-    This hook is still *experimental*, so its parameters or even the hook itself might
+        This hook is **experimental**, so its parameters or even the hook itself might
         be changed/removed without warning in any future pytest release.
 
-    It should be enabled using the `enable_assertion_pass_hook` ini-file option.
-    Remember to clean the .pyc files in your project directory and interpreter libraries.
-
         If you find this hook useful, please share your feedback opening an issue.
     """