Clarify that session.close() is like reset

Fixes: #5517
Change-Id: I86809cf84de3ec19a279ae13f4e5e71336d8b359

diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst
index ecf76ae63e354116fc85801120af27730e4bfe8e..78f8f3234fb58ed33251f6755c7dec83c29faa62 100644 (file)
--- a/doc/build/orm/session_basics.rst
+++ b/doc/build/orm/session_basics.rst
@@ -581,10 +581,16 @@ be simply closed and discarded).   See the FAQ entry at
 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.
 
 It's recommended that the scope of a :class:`_orm.Session` be limited by
 a call to :meth:`_orm.Session.close` at the end, especially if the