add TODO, docs for ILB, simplify commitWithResponse

Author: bshaffer

Spanner/src/Operation.php

@@ -161,7 +161,14 @@ public function commitWithResponse(Session $session, array $mutations, array $op
             'session' => $session->name(),
             'mutations' => $mutations
         ];
-        $commitRequest = $this->formatSingleUseTransactionOptions($commitRequest);
+
+        // Configure Single Use Transaction options
+        // @TODO: Find out why we do this
+        if (isset($commitRequest['singleUseTransaction'])) {
+            $commitRequest['singleUseTransaction'] = ['readWrite' => []];
+            // CommitRequest ignores singleUseTransaction if the transactionId is set
+            unset($commitRequest['transactionId']);
+        }
 
         $request = $this->serializer->decodeMessage(new CommitRequest(), $commitRequest);
         $response = $this->spannerClient->commit($request, $callOptions + [
@@ -1078,21 +1085,6 @@ private function streamingRead(array $args, array $callOptions): \Generator
         return $this->handleResponse($response);
     }
 
-    /**
-     * @param array $args
-     * @return array
-     */
-    private function formatSingleUseTransactionOptions(array $args): array
-    {
-        if (isset($args['singleUseTransaction'])) {
-            $args['singleUseTransaction'] = ['readWrite' => []];
-            // request ignores singleUseTransaction even if the transactionId is set to null
-            unset($args['transactionId']);
-        }
-
-        return $args;
-    }
-
     /**
      * @param array $args
      *

Spanner/src/Transaction.php

@@ -85,7 +85,8 @@ class Transaction implements TransactionalReadInterface
      *     @type bool $isRetry Whether the transaction will automatically retry or not.
      *     @type string $tag A transaction tag. Requests made using this transaction will
      *           use this as the transaction tag.
-     *     @type array $begin The begin Transaction options. See {@see V1\TransactionOptions}.
+     *     @type array $begin The begin Transaction options, for using inline begin transactions.
+     *           See {@see V1\TransactionOptions}.
      *     @type array $requestOptions See {@see V1\RequestOptions}.
      *     @type array $transactionOptions See {@see V1\TransactionOptions}.
      * }
@@ -412,8 +413,7 @@ public function commit(array $options = []): Timestamp
         }
 
         // For commit, A transaction ID is mandatory for non-single-use transactions,
-        // and the `begin` option is not supported.
-        // @TODO: Find out why the `begin` option is not supported for calling the `beginTransaction` RPC
+        // and the `begin` option is not supported (because `begin` is only used in "inline begin transactions")
         if (empty($this->transactionId) && isset($this->transactionSelector['begin'])) {
             $operationTransactionOptions = [
                 'requestOptions' => $this->requestOptions,
@@ -446,6 +446,7 @@ public function commit(array $options = []): Timestamp
 
         $t = $this->transactionOptions($options);
 
+        // @TODO find out what this is and clean it up
         $options[$t[1]] = $t[0];
 
         $res = $this->operation->commitWithResponse($this->session, $this->pluck('mutations', $options), $options);