From 3afee36ebb0720bb15f4ca67ea0f1305434e1cc7 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 26 Jun 2019 19:10:54 -0300
Subject: [PATCH] Improve docs and reference

---
 changelog/3457.feature.rst |  6 ++++--
 doc/en/reference.rst       |  7 +++----
 src/_pytest/hookspec.py    | 25 ++++++++++++++++++-------
 3 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/changelog/3457.feature.rst b/changelog/3457.feature.rst
index 3f6765144..c30943070 100644
--- a/changelog/3457.feature.rst
+++ b/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.
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 6750b17f0..5abb01f50 100644
--- a/doc/en/reference.rst
+++ b/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
diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py
index 268348eac..9e6d13fab 100644
--- a/src/_pytest/hookspec.py
+++ b/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,13 +514,10 @@ def pytest_assertion_pass(item, lineno, orig, expl):
 
     .. note::
 
-    This hook is still *experimental*, so its parameters or even the hook itself might
-    be changed/removed without warning in any future pytest release.
+        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.
+        If you find this hook useful, please share your feedback opening an issue.
     """