more docs on this

2 files changed, 17 insertions, 13 deletions

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 9068a1332..39c68f0aa 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -356,12 +356,12 @@ def relationship(argument, secondary=None, **kwargs):
        
       Detailed discussion of loader strategies is at :ref:`loading_toplevel`.
     
-    :param load_on_pending:
+    :param load_on_pending=False:
       Indicates loading behavior for transient or pending parent objects.
       
-      This is an advanced user feature that will cause the lazy-loader to
+      When set to ``True``, causes the lazy-loader to
       issue a query for a parent object that is not persistent, meaning it has
-      never been flushed. This may take effect for a pending object when
+      never been flushed.  This may take effect for a pending object when
       autoflush is disabled, or for a transient object that has been
       "attached" to a :class:`.Session` but is not part of its pending
       collection. Attachment of transient objects to the session without
@@ -373,6 +373,12 @@ def relationship(argument, secondary=None, **kwargs):
       object is ultimately flushed, only the user-specific foreign key 
       attributes will be part of the modified state.
       
+      The load_on_pending flag does not improve behavior
+      when the ORM is used normally - object references should be constructed
+      at the object level, not at the foreign key level, so that they
+      are present in an ordinary way before flush() proceeds.  This flag
+      is not not intended for general use.
+      
       New in 0.6.5.
       
     :param order_by:
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 3bf8280f6..6c5e8c81c 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -633,16 +633,14 @@ class Query(object):
 
     @_generative()
     def populate_existing(self):
-        """Return a Query that will refresh all instances loaded.
-
-        This includes all entities accessed from the database, including
-        secondary entities, eagerly-loaded collection items.
-
-        All changes present on entities which are already present in the
-        session will be reset and the entities will all be marked "clean".
-
-        An alternative to populate_existing() is to expire the Session
-        fully using session.expire_all().
+        """Return a :class:`Query` that will expire and refresh all instances 
+        as they are loaded, or reused from the current :class:`.Session`.
+        
+        :meth:`.populate_existing` does not improve behavior when 
+        the ORM is used normally - the :class:`.Session` object's usual 
+        behavior of maintaining a transaction and expiring all attributes
+        after rollback or commit handles object state automatically.
+        This method is not intended for general use.
 
         """
         self._populate_existing = True