Improve doc string around tx functions (#778)

`session.read_transaction` and `session.write_transaction` were slightly wrong
about the tx class passed to the tx function. Furthermore, they are now more
explicit about the idempotency required from tx funcs.

Author: robsdedude

neo4j/_async/work/session.py

@@ -543,11 +543,12 @@ async def read_transaction(
             This does not necessarily imply access control, see the session
             configuration option :ref:`default-access-mode-ref`.
 
-        This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
-        Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once.
-
-        Managed transactions should not generally be explicitly committed
-        (via ``await tx.commit()``).
+        This transaction will automatically be committed when the function
+        returns, unless an exception is thrown during query execution or by
+        the user code. Note, that this function performs retries and that the
+        supplied `transaction_function` might get invoked more than once.
+        Therefore, it needs to be idempotent (i.e., have the same effect,
+        regardless if called once or many times).
 
         Example::
 
@@ -582,8 +583,8 @@ async def get_two_tx(tx):
         :param transaction_function: a function that takes a transaction as an
             argument and does work with the transaction.
             `transaction_function(tx, *args, **kwargs)` where `tx` is a
-            :class:`.AsyncTransaction`.
-        :param args: arguments for the `transaction_function`
+            :class:`.AsyncManagedTransaction`.
+        :param args: additional arguments for the `transaction_function`
         :param kwargs: key word arguments for the `transaction_function`
 
         :raises SessionError: if the session has been closed.
@@ -607,10 +608,12 @@ async def write_transaction(
             This does not necessarily imply access control, see the session
             configuration option :ref:`default-access-mode-ref`.
 
-        This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
-        Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once.
-
-        Managed transactions should not generally be explicitly committed (via tx.commit()).
+        This transaction will automatically be committed when the function
+        returns unless, an exception is thrown during query execution or by
+        the user code. Note, that this function performs retries and that the
+        supplied `transaction_function` might get invoked more than once.
+        Therefore, it needs to be idempotent (i.e., have the same effect,
+        regardless if called once or many times).
 
         Example::
 
@@ -626,8 +629,8 @@ async def create_node_tx(tx, name):
         :param transaction_function: a function that takes a transaction as an
             argument and does work with the transaction.
             `transaction_function(tx, *args, **kwargs)` where `tx` is a
-            :class:`.AsyncTransaction`.
-        :param args: key word arguments for the `transaction_function`
+            :class:`.AsyncManagedTransaction`.
+        :param args: additional arguments for the `transaction_function`
         :param kwargs: key word arguments for the `transaction_function`
 
         :raises SessionError: if the session has been closed.

neo4j/_sync/work/session.py

@@ -543,11 +543,12 @@ def read_transaction(
             This does not necessarily imply access control, see the session
             configuration option :ref:`default-access-mode-ref`.
 
-        This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
-        Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once.
-
-        Managed transactions should not generally be explicitly committed
-        (via ``tx.commit()``).
+        This transaction will automatically be committed when the function
+        returns, unless an exception is thrown during query execution or by
+        the user code. Note, that this function performs retries and that the
+        supplied `transaction_function` might get invoked more than once.
+        Therefore, it needs to be idempotent (i.e., have the same effect,
+        regardless if called once or many times).
 
         Example::
 
@@ -582,8 +583,8 @@ def get_two_tx(tx):
         :param transaction_function: a function that takes a transaction as an
             argument and does work with the transaction.
             `transaction_function(tx, *args, **kwargs)` where `tx` is a
-            :class:`.Transaction`.
-        :param args: arguments for the `transaction_function`
+            :class:`.ManagedTransaction`.
+        :param args: additional arguments for the `transaction_function`
         :param kwargs: key word arguments for the `transaction_function`
 
         :raises SessionError: if the session has been closed.
@@ -607,10 +608,12 @@ def write_transaction(
             This does not necessarily imply access control, see the session
             configuration option :ref:`default-access-mode-ref`.
 
-        This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
-        Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once.
-
-        Managed transactions should not generally be explicitly committed (via tx.commit()).
+        This transaction will automatically be committed when the function
+        returns unless, an exception is thrown during query execution or by
+        the user code. Note, that this function performs retries and that the
+        supplied `transaction_function` might get invoked more than once.
+        Therefore, it needs to be idempotent (i.e., have the same effect,
+        regardless if called once or many times).
 
         Example::
 
@@ -626,8 +629,8 @@ def create_node_tx(tx, name):
         :param transaction_function: a function that takes a transaction as an
             argument and does work with the transaction.
             `transaction_function(tx, *args, **kwargs)` where `tx` is a
-            :class:`.Transaction`.
-        :param args: key word arguments for the `transaction_function`
+            :class:`.ManagedTransaction`.
+        :param args: additional arguments for the `transaction_function`
         :param kwargs: key word arguments for the `transaction_function`
 
         :raises SessionError: if the session has been closed.