replace "e.g.::" with more context regarding attribute events example

Fixes: #7613
Change-Id: I28a9577587399c41afd53fbd026003667654c3fc

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index d31bff31a2a9dba78b20218615a7a89fdbfe2849..dc049891a1164bb80cc5cc16d0fd986e71a8b460 100644 (file)
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -2154,7 +2154,8 @@ class AttributeEvents(event.Events):
     These are typically defined on the class-bound descriptor for the
     target class.
 
-    e.g.::
+    For example, to register a listener that will receive the
+    :meth:`_orm.AttributeEvents.append` event::
 
         from sqlalchemy import event
 
@@ -2165,7 +2166,8 @@ class AttributeEvents(event.Events):
 
     Listeners have the option to return a possibly modified version of the
     value, when the :paramref:`.AttributeEvents.retval` flag is passed to
-    :func:`.event.listen` or :func:`.event.listens_for`::
+    :func:`.event.listen` or :func:`.event.listens_for`, such as below,
+    illustrated using the :meth:`_orm.AttributeEvents.set` event::
 
         def validate_phone(target, value, oldvalue, initiator):
             "Strip non-numeric characters from a phone number"