docs: clarify how async updates can overtake each other

README.md

@@ -19,7 +19,7 @@ If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file:
  <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>libraries-bom</artifactId>
- <version>26.50.0</version>
+ <version>26.53.0</version>
  <type>pom</type>
  <scope>import</scope>
  </dependency>

google-cloud-spanner/src/main/java/com/google/cloud/spanner/TransactionContext.java

@@ -121,11 +121,11 @@ default ApiFuture<Void> bufferAsync(Iterable<Mutation> mutations) {
  /**
  * Same as {@link #executeUpdate(Statement,UpdateOption...)}, but is guaranteed to be
  * non-blocking. If multiple asynchronous update statements are submitted to the same read/write
- * transaction, the statements are guaranteed to be submitted to Cloud Spanner in the order that
- * they were submitted in the client. This does however not guarantee that an asynchronous update
- * statement will see the results of all previously submitted statements, as the execution of the
- * statements can be parallel. If you rely on the results of a previous statement, you should
- * block until the result of that statement is known and has been returned to the client.
+ * transaction, the statements are guaranteed to be sent to Cloud Spanner in the order that they
+ * were submitted in the client. This does however not guarantee that Spanner will receive the
+ * requests in the same order as they were sent, as requests that are sent partly in parallel can
+ * overtake each other. It is therefore recommended to block until an update statement has
+ * returned a result before sending the next update statement.
  */
  ApiFuture<Long> executeUpdateAsync(Statement statement, UpdateOption... options);
 
@@ -181,11 +181,11 @@ default ResultSet analyzeUpdateStatement(
  /**
  * Same as {@link #batchUpdate(Iterable, UpdateOption...)}, but is guaranteed to be non-blocking.
  * If multiple asynchronous update statements are submitted to the same read/write transaction,
- * the statements are guaranteed to be submitted to Cloud Spanner in the order that they were
- * submitted in the client. This does however not guarantee that an asynchronous update statement
- * will see the results of all previously submitted statements, as the execution of the statements
- * can be parallel. If you rely on the results of a previous statement, you should block until the
- * result of that statement is known and has been returned to the client.
+ * the statements are guaranteed to be sent to Cloud Spanner in the order that they were submitted
+ * in the client. This does however not guarantee that Spanner will receive the requests in the
+ * same order as they were sent, as requests that are sent partly in parallel can overtake each
+ * other. It is therefore recommended to block until an update statement has returned a result
+ * before sending the next update statement.
  */
  ApiFuture<long[]> batchUpdateAsync(Iterable<Statement> statements, UpdateOption... options);
 }