Fix links and update verbiage for reset_on_return

Change-Id: I642056b78570b44fdefe7f0874a8e4c720389f14
(cherry picked from commit d8bb208a85f6366c58426a85b3d4ec1d6e43ac6c)

2 files changed, 18 insertions, 20 deletions

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index e23967412..4315e6a33 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -357,13 +357,14 @@ def create_engine(*args, **kwargs):
 
             :ref:`pool_setting_recycle`
 
-    :param pool_reset_on_return='rollback': set the "reset on return"
-        behavior of the pool, which is whether ``rollback()``,
-        ``commit()``, or nothing is called upon connections
-        being returned to the pool.  See the docstring for
-        ``reset_on_return`` at :class:`.Pool`.
+    :param pool_reset_on_return='rollback': set the
+        :paramref:`.Pool.reset_on_return` parameter of the underlying
+        :class:`.Pool` object, which can be set to the values
+        ``"rollback"``, ``"commit"``, or ``None``.
 
-        .. versionadded:: 0.7.6
+        .. seealso::
+
+            :paramref:`.Pool.reset_on_return`
 
     :param pool_timeout=30: number of seconds to wait before giving
         up on getting a connection from the pool. This is only used
diff --git a/lib/sqlalchemy/pool.py b/lib/sqlalchemy/pool.py
index 7cd2c3d0d..f1f278e91 100644
--- a/lib/sqlalchemy/pool.py
+++ b/lib/sqlalchemy/pool.py
@@ -178,25 +178,22 @@ class Pool(log.Identified):
             any data changes present on the transaction
             are committed unconditionally.
           * ``None`` - don't do anything on the connection.
-            This setting should only be made on a database
+            This setting should generally only be made on a database
             that has no transaction support at all,
-            namely MySQL MyISAM.   By not doing anything,
-            performance can be improved.   This
-            setting should **never be selected** for a
-            database that supports transactions,
-            as it will lead to deadlocks and stale
-            state.
-          * ``"none"`` - same as ``None``
-
-            .. versionadded:: 0.9.10
+            namely MySQL MyISAM; when used on this backend, performance
+            can be improved as the "rollback" call is still expensive on
+            MySQL.   It is **strongly recommended** that this setting not be
+            used for transaction-supporting databases in conjunction with
+            a persistent pool such as :class:`.QueuePool`, as it opens
+            the possibility for connections still in a transaction to be
+            idle in the pool.   The setting may be appropriate in the
+            case of :class:`.NullPool` or special circumstances where
+            the connection pool in use is not being used to maintain connection
+            lifecycle.
 
           * ``False`` - same as None, this is here for
             backwards compatibility.
 
-          .. versionchanged:: 0.7.6
-              :paramref:`.Pool.reset_on_return` accepts ``"rollback"``
-              and ``"commit"`` arguments.
-
         :param events: a list of 2-tuples, each of the form
          ``(callable, target)`` which will be passed to :func:`.event.listen`
          upon construction.   Provided here so that event listeners