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

Fixes: #7613
Change-Id: I28a9577587399c41afd53fbd026003667654c3fc
(cherry picked from commit 5e3357c70e419c244156ac3885b2cf784b5b3fc0)

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 1514a2d433d0c4aecb6640a4423a85e383bddcd6..9a6acbd4225bf56dc6eb693fc4c06e326d67dc2f 100644 (file)
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -2142,7 +2142,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
 
@@ -2153,7 +2154,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"