doc updates

2 files changed, 47 insertions, 7 deletions

diff --git a/doc/build/orm/loading.rst b/doc/build/orm/loading.rst
index 3ef2afa44..b62fac488 100644
--- a/doc/build/orm/loading.rst
+++ b/doc/build/orm/loading.rst
@@ -122,7 +122,7 @@ To reference a relationship that is deeper than one level, separate the names by
     session.query(Parent).options(joinedload('foo.bar.bat')).all()
 
 When using dot-separated names with :func:`~sqlalchemy.orm.joinedload` or
-:func:`~sqlalchemy.orm.subqueryload`, option applies **only** to the actual
+:func:`~sqlalchemy.orm.subqueryload`, the option applies **only** to the actual
 attribute named, and **not** its ancestors. For example, suppose a mapping
 from ``A`` to ``B`` to ``C``, where the relationships, named ``atob`` and
 ``btoc``, are both lazy-loading. A statement like the following:
@@ -131,21 +131,26 @@ from ``A`` to ``B`` to ``C``, where the relationships, named ``atob`` and
 
     session.query(A).options(joinedload('atob.btoc')).all()
 
-will load only ``A`` objects to start.  When the ``atob`` attribute on each ``A`` is accessed, the returned ``B`` objects will *eagerly* load their ``C`` objects.
+will load only ``A`` objects to start. When the ``atob`` attribute on each
+``A`` is accessed, the returned ``B`` objects will *eagerly* load their ``C``
+objects.
 
-Therefore, to modify the eager load to load both ``atob`` as well as ``btoc``, place joinedloads for both:
+Therefore, to modify the eager load to load both ``atob`` as well as ``btoc``,
+place joinedloads for both:
 
 .. sourcecode:: python+sql
 
     session.query(A).options(joinedload('atob'), joinedload('atob.btoc')).all()
 
-or more simply just use :func:`~sqlalchemy.orm.joinedload_all` or :func:`~sqlalchemy.orm.subqueryload_all`:
+or more simply just use :func:`~sqlalchemy.orm.joinedload_all` or
+:func:`~sqlalchemy.orm.subqueryload_all`:
 
 .. sourcecode:: python+sql
 
     session.query(A).options(joinedload_all('atob.btoc')).all()
 
-There are two other loader strategies available, **dynamic loading** and **no loading**; these are described in :ref:`largecollections`.
+There are two other loader strategies available, **dynamic loading** and **no
+loading**; these are described in :ref:`largecollections`.
 
 The Zen of Eager Loading
 -------------------------
diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 8e4d4a147..36f4a43fb 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -62,8 +62,43 @@ class InstrumentationEvents(event.Events):
 class InstanceEvents(event.Events):
     """Define events specific to object lifecycle.
 
-    Instance-level don't automatically propagate their associations
-    to subclasses.
+    e.g.::
+
+        from sqlalchemy import event
+
+        def my_load_listener(target, context):
+            print "on load!"
+
+        event.listen(SomeMappedClass, 'load', my_load_listener)
+
+    Available targets include mapped classes, instances of
+    :class:`.Mapper` (i.e. returned by :func:`.mapper`,
+    :func:`.class_mapper` and similar), as well as the
+    :class:`.Mapper` class and :func:`.mapper` function itself
+    for global event reception::
+
+        from sqlalchemy.orm import mapper
+
+        def some_listener(target, context):
+            log.debug("Instance %s being loaded" % target)
+
+        # attach to all mappers
+        event.listen(mapper, 'load', some_listener)
+
+    Instance events are closely related to mapper events, but
+    are more specific to the instance and its instrumentation,
+    rather than its system of persistence.
+
+    When using :class:`.InstanceEvents`, several modifiers are
+    available to the :func:`.event.listen` function.
+
+    :param propagate=False: When True, the event listener should 
+       be applied to all inheriting mappers as well as the 
+       mapper which is the target of this listener.
+    :param raw=False: When True, the "target" argument passed
+       to applicable event listener functions will be the 
+       instance's :class:`.InstanceState` management
+       object, rather than the mapped instance itself.
 
     """
     @classmethod