documentation updates

Change-Id: I43d0e8de1f90abcff4b278637808d1ebc8fd6c97

2 files changed, 25 insertions, 9 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 906de08bb..a748270d0 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -31,11 +31,14 @@ _EMPTY_EXECUTION_OPTS = util.immutabledict()
 class Connection(Connectable):
     """Provides high-level functionality for a wrapped DB-API connection.
 
-    Provides execution support for string-based SQL statements as well as
-    :class:`_expression.ClauseElement`, :class:`.Compiled` and
-    :class:`.DefaultGenerator`
-    objects. Provides a :meth:`begin` method to return :class:`.Transaction`
-    objects.
+    **This is the SQLAlchemy 1.x.x version** of the :class:`_engine.Connection`
+    class.   For the :term:`2.0 style` version, which features some API
+    differences, see :class:`_future.Connection`.
+
+    The :class:`_engine.Connection` object is procured by calling
+    the :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine`
+    object, and provides services for execution of SQL statements as well
+    as transaction control.
 
     The Connection object is **not** thread-safe.  While a Connection can be
     shared among threads using properly synchronized access, it is still
@@ -2581,6 +2584,10 @@ class Engine(Connectable, log.Identified):
     :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a
     source of database connectivity and behavior.
 
+    This is the **SQLAlchemy 1.x version** of :class:`_engine.Engine`.  For
+    the :term:`2.0 style` version, which includes  some API differences,
+    see :class:`_future.Engine`.
+
     An :class:`_engine.Engine` object is instantiated publicly using the
     :func:`~sqlalchemy.create_engine` function.
 
diff --git a/lib/sqlalchemy/future/engine.py b/lib/sqlalchemy/future/engine.py
index bfdcdfc7f..efd0b0eab 100644
--- a/lib/sqlalchemy/future/engine.py
+++ b/lib/sqlalchemy/future/engine.py
@@ -24,13 +24,20 @@ def create_engine(*arg, **kw):
 class Connection(_LegacyConnection):
     """Provides high-level functionality for a wrapped DB-API connection.
 
+    The :class:`_future.Connection` object is procured by calling
+    the :meth:`_future.Engine.connect` method of the :class:`_future.Engine`
+    object, and provides services for execution of SQL statements as well
+    as transaction control.
+
     **This is the SQLAlchemy 2.0 version** of the :class:`_engine.Connection`
     class.   The API and behavior of this object is largely the same, with the
     following differences in behavior:
 
-    * The result object returned for results is the :class:`_engine.Result`
-      object.  This object has a slightly different API and behavior than the
-      prior :class:`_engine.CursorResult` object.
+    * The result object returned for results is the
+      :class:`_engine.CursorResult`
+      object, which is a subclass of the :class:`_engine.Result`.
+      This object has a slightly different API and behavior than the
+      :class:`_engine.LegacyCursorResult` returned for 1.x style usage.
 
     * The object has :meth:`_future.Connection.commit` and
       :meth:`_future.Connection.rollback` methods which commit or roll back
@@ -61,7 +68,9 @@ class Connection(_LegacyConnection):
       any special instructions for the SAVEPOINT (this will typically have the
       effect that one desires).
 
-    * There are no "nested" connections or transactions.
+    * The :class:`_future.Connection` object does not support "branching",
+      which was a pattern by which a sub "connection" would be used that
+      refers to this connection as a parent.