fixed up docs for execution_options() across all three locations.

3 files changed, 32 insertions, 15 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 46907dfcf..ea6282954 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -767,15 +767,20 @@ class Connection(Connectable):
         return self.engine.Connection(self.engine, self.__connection, _branch=True)
     
     def execution_options(self, **opt):
-        """Add keyword options to a Connection generatively.
+        """ Set non-SQL options for the connection which take effect during execution.
         
-        Experimental.  May change the name/signature at 
-        some point.
-        
-        If made public, strongly consider the name
-        "options()" so as to be consistent with
-        orm.Query.options().
+        The method returns a copy of this :class:`Connection` which references
+        the same underlying DBAPI connection, but also defines the given execution
+        options which will take effect for a call to :meth:`execute`.  As the new 
+        :class:`Connection` references the same underlying resource, it is probably
+        best to ensure that the copies would be discarded immediately, which
+        is implicit if used as in::
         
+            result = connection.execution_options(stream_results=True).execute(stmt)
+            
+        The options are the same as those accepted by 
+        :meth:`sqlalchemy.sql.expression.Executable.execution_options`.
+
         """
         return self.engine.Connection(
                     self.engine, self.__connection,
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index a477ea544..0f68e0a41 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -691,14 +691,14 @@ class Query(object):
 
     @_generative()
     def execution_options(self, **kwargs):
-        """ Set non-SQL options for the resulting statement, 
-        such as dialect-specific options.
+        """ Set non-SQL options which take effect during execution.
         
-        The only option currently understood is ``stream_results=True``, 
-        only used by Psycopg2 to enable "server side cursors".  This option
-        only has a useful effect if used in conjunction with
-        :meth:`~sqlalchemy.orm.query.Query.yield_per()`,
-        which currently sets ``stream_results`` to ``True`` automatically.
+        The options are the same as those accepted by 
+        :meth:`sqlalchemy.sql.expression.Executable.execution_options`.
+        
+        Note that the ``stream_results`` execution option is enabled
+        automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()`
+        method is used.
 
         """
         _execution_options = self._execution_options.copy()
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index c559f3850..2e0a0b803 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -2235,7 +2235,13 @@ class _Generative(object):
 
 
 class Executable(_Generative):
-    """Mark a ClauseElement as supporting execution."""
+    """Mark a ClauseElement as supporting execution.
+    
+    :class:`Executable` is a superclass for all "statement" types
+    of objects, including :func:`select`, :func:`delete`, :func:`update`,
+    :func:`insert`, :func:`text`.
+     
+    """
 
     supports_execution = True
     _execution_options = util.frozendict()
@@ -2263,6 +2269,12 @@ class Executable(_Generative):
           of many DBAPIs.  The flag is currently understood only by the
           psycopg2 dialect.
 
+        See also:
+        
+            :meth:`sqlalchemy.engine.base.Connection.execution_options()`
+
+            :meth:`sqlalchemy.orm.query.Query.execution_options()`
+            
         """
         self._execution_options = self._execution_options.union(kw)