feat: Multiplexed sessions - Make deprecation comments a bit more clear.

Signed-off-by: Taylor Curran <taylor.curran@improving.com>

Author: currantw

google/cloud/spanner_v1/database.py

@@ -831,8 +831,9 @@ def _nth_client_id(self):
     def session(self, labels=None, database_role=None):
         """Factory to create a session for this database.
 
-        Deprecated. Sessions should be checked out using context
-        managers, rather than retrieved directly from the database.
+        Deprecated. Sessions should be checked out indirectly using context
+        managers or :meth:`~google.cloud.spanner_v1.database.Database.run_in_transaction`,
+        rather than built directly from the database.
 
         :type labels: dict (str -> str) or None
         :param labels: (Optional) user-assigned labels for the session.

google/cloud/spanner_v1/pool.py

@@ -138,8 +138,9 @@ def _new_session(self):
     def session(self, **kwargs):
         """Check out a session from the pool.
 
-        Deprecated. Sessions should be checked out using context
-        managers, rather than directly from the pool.
+        Deprecated. Sessions should be checked out indirectly using context
+        managers or :meth:`~google.cloud.spanner_v1.database.Database.run_in_transaction`,
+        rather than checked out directly from the pool.
 
         :param kwargs: (optional) keyword arguments, passed through to
                        the returned checkout.
@@ -796,8 +797,9 @@ def begin_pending_transactions(self):
 class SessionCheckout(object):
     """Context manager: hold session checked out from a pool.
 
-    Deprecated. Sessions should be checked out using context
-    managers, rather than directly from the pool.
+    Deprecated. Sessions should be checked out indirectly using context
+    managers or :meth:`~google.cloud.spanner_v1.database.Database.run_in_transaction`,
+    rather than checked out directly from the pool.
 
     :type pool: concrete subclass of
         :class:`~google.cloud.spanner_v1.pool.AbstractSessionPool`