Clarify that session.close() is like reset

This is a manual edit, not really a cherry-pick, but the
below ref is where this is from.

Fixes: #5517
Change-Id: I86809cf84de3ec19a279ae13f4e5e71336d8b359
(cherry picked from commit 7277c12e4d1bdc9647b9b306d89b5847d1c5a4d7)

diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst
index df157c17c978cf9fd0dddcd38bb389dccfd6bee8..40715a704919d8d98be2ef714f6686f5411a79fb 100644 (file)
--- a/doc/build/orm/session_basics.rst
+++ b/doc/build/orm/session_basics.rst
@@ -813,9 +813,15 @@ reset the state of the :class:`~sqlalchemy.orm.session.Session`.
 Closing
 -------
 
-The :meth:`~.Session.close` method issues a
-:meth:`~.Session.expunge_all`, and :term:`releases` any
-transactional/connection resources. When connections are returned to the
-connection pool, transactional state is rolled back as well.
+The :meth:`~.Session.close` method issues a :meth:`~.Session.expunge_all` which
+removes all ORM-mapped objects from the session, and :term:`releases` any
+transactional/connection resources from the :class:`_engine.Engine` object(s)
+to which it is bound.   When connections are returned to the connection pool,
+transactional state is rolled back as well.
+
+When the :class:`_orm.Session` is closed, it is essentially in the
+original state as when it was first constructed, and **may be used again**.
+In this sense, the :meth:`_orm.Session.close` method is more like a "reset"
+back to the clean state and not as much like a "database close" method.