docstrings for instances()/iterate_instances()

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index df775a177289e2aa3c27e5f55b34349a467868ad..43a7c41a3a226f3499ccc0c28ad4ce11875becbf 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1042,9 +1042,26 @@ class Query(object):
         return self.iterate_instances(result, querycontext)
 
     def instances(self, cursor, __context=None):
+        """Given a ResultProxy cursor as returned by connection.execute(), return an ORM result as a list.
+
+        e.g.::
+        
+            result = engine.execute("select * from users")
+            users = session.query(User).instances(result)
+
+        """
         return list(self.iterate_instances(cursor, __context))
 
     def iterate_instances(self, cursor, __context=None):
+        """Given a ResultProxy cursor as returned by connection.execute(), return an ORM result as an iterator.
+        
+        e.g.::
+        
+            result = engine.execute("select * from users")
+            for u in session.query(User).iterate_instances(result):
+                print u
+
+        """
         session = self.session
 
         context = __context