update docstrings

Author: daniel-sanche

google/cloud/datastore/batch.py

@@ -281,7 +281,9 @@ def begin(self):
 
         This method is called automatically when entering a with
         statement, however it can be called explicitly if you don't want
-        to use a context manager.
+        to use a context manager. If used outside a context manager,
+        `client.get` calls targeting the batch and commit/rollback calls
+        will need to be managed explicitly as well
 
         Overridden by :class:`google.cloud.datastore.transaction.Transaction`.
 
@@ -365,6 +367,10 @@ def rollback(self):
 
         Marks the batch as aborted (can't be used again).
 
+        This is called automatically upon exiting a with statement,
+        however it can be called explicitly if you don't want to use a
+        context manager.
+
         Overridden by :class:`google.cloud.datastore.transaction.Transaction`.
 
         :raises: :class:`~exceptions.ValueError` if the batch is not

google/cloud/datastore/client.py

@@ -407,7 +407,7 @@ def _pop_batch(self):
 
     @property
     def current_batch(self):
-        """Currently-active batch.
+        """Currently-active batch, if within the scope of a Batch context manager.
 
         :rtype: :class:`google.cloud.datastore.batch.Batch`, or an object
                 implementing its API, or ``NoneType`` (if no batch is active).
@@ -417,7 +417,8 @@ def current_batch(self):
 
     @property
     def current_transaction(self):
-        """Currently-active transaction.
+        """Currently-active transaction, if within the scope of a Transaction
+        context manager.
 
         :rtype: :class:`google.cloud.datastore.transaction.Transaction`, or an
                 object implementing its API, or ``NoneType`` (if no transaction

google/cloud/datastore/transaction.py

@@ -212,7 +212,9 @@ def begin(self, retry=None, timeout=None):
 
         This method is called automatically when entering a with
         statement, however it can be called explicitly if you don't want
-        to use a context manager.
+        to use a context manager. If used outside a context manager,
+        `client.get` calls targeting the transaction and commit/rollback calls
+        will need to be managed explicitly as well.
 
         :type retry: :class:`google.api_core.retry.Retry`
         :param retry: