Improve documentation for connection pool logging

Also do a general pass for logging + doc formatting,
add more cross-linking and remove obsolete information such
as "echo_uow"/

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Fixes: #4571
Closes: #4583
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/4583
Pull-request-sha: e98ad34eca7e9f59fb07cd8b7ec317c1cb989848

Change-Id: I03f7354a4ef55fd8b6a51d03a280579f36e8a06c

1 files changed, 14 insertions, 5 deletions

diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py
index ea73f08d4..f5585c651 100644
--- a/lib/sqlalchemy/pool/base.py
+++ b/lib/sqlalchemy/pool/base.py
@@ -105,11 +105,20 @@ class Pool(log.Identified):
           "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
           id.
 
-        :param echo: If True, connections being pulled and retrieved
-          from the pool will be logged to the standard output, as well
-          as pool sizing information.  Echoing can also be achieved by
-          enabling logging for the "sqlalchemy.pool"
-          namespace. Defaults to False.
+        :param echo: if True, the connection pool will log
+         informational output such as when connections are invalidated
+         as well as when connections are recycled to the default log handler,
+         which defaults to ``sys.stdout`` for output..   If set to the string
+         ``"debug"``, the logging will include pool checkouts and checkins.
+
+         The :paramref:`.Pool.echo` parameter can also be set from the
+         :func:`.create_engine` call by using the
+         :paramref:`.create_engine.echo_pool` parameter.
+
+         .. seealso::
+
+             :ref:`dbengine_logging` - further detail on how to configure
+             logging.
 
         :param use_threadlocal: If set to True, repeated calls to
           :meth:`connect` within the same application thread will be