spanner: clearify docs on Aborted tx

Clearify documentation on what an Aborted error is and when it might
happen.

Updates #1939

Change-Id: I1a985a4b204407eabf5f07b94dfb0937e997b093
Reviewed-on: https://code-review.googlesource.com/c/gocloud/+/55592
Reviewed-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Hengfeng Li <hengfeng@google.com>

spanner/doc.go

@@ -275,16 +275,20 @@ To apply a list of mutations to the database, use Apply:
     _, err := client.Apply(ctx, []*spanner.Mutation{m1, m2, m3})
 
 If you need to read before writing in a single transaction, use a
-ReadWriteTransaction. ReadWriteTransactions may abort and need to be retried.
-You pass in a function to ReadWriteTransaction, and the client will handle the
-retries automatically. Use the transaction's BufferWrite method to buffer
-mutations, which will all be executed at the end of the transaction:
+ReadWriteTransaction. ReadWriteTransactions may be aborted automatically by the
+backend and need to be retried. You pass in a function to ReadWriteTransaction,
+and the client will handle the retries automatically. Use the transaction's
+BufferWrite method to buffer mutations, which will all be executed at the end
+of the transaction:
 
     _, err := client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
         var balance int64
         row, err := txn.ReadRow(ctx, "Accounts", spanner.Key{"alice"}, []string{"balance"})
         if err != nil {
-            // This function will be called again if this is an IsAborted error.
+            // The transaction function will be called again if the error code
+            // of this error is Aborted. The backend may automatically abort
+            // any read/write transaction if it detects a deadlock or other
+            // problems.
             return err
         }
         if err := row.Column(0, &balance); err != nil {
@@ -299,7 +303,7 @@ mutations, which will all be executed at the end of the transaction:
         txn.BufferWrite([]*spanner.Mutation{m})
 
         // The buffered mutation will be committed.  If the commit
-        // fails with an IsAborted error, this function will be called
+        // fails with an Aborted error, this function will be called
         // again.
         return nil
     })

spanner/integration_test.go

@@ -1647,7 +1647,7 @@ func TestIntegration_TransactionRunner(t *testing.T) {
 		var b int64
 		r, e := tx.ReadRow(ctx, "Accounts", Key{int64(key)}, []string{"Balance"})
 		if e != nil {
-			if expectAbort && !isAbortErr(e) {
+			if expectAbort && !isAbortedErr(e) {
 				t.Errorf("ReadRow got %v, want Abort error.", e)
 			}
 			// Verify that we received and are able to extract retry info from

spanner/transaction.go

@@ -1024,7 +1024,7 @@ func (t *ReadWriteTransaction) runInTransaction(ctx context.Context, f func(cont
 		errDuringCommit = err != nil
 	}
 	if err != nil {
-		if isAbortErr(err) {
+		if isAbortedErr(err) {
 			// Retry the transaction using the same session on ABORT error.
 			// Cloud Spanner will create the new transaction with the previous
 			// one's wound-wait priority.
@@ -1098,7 +1098,7 @@ func (t *writeOnlyTransaction) applyAtLeastOnce(ctx context.Context, ms ...*Muta
 			},
 			Mutations: mPb,
 		})
-		if err != nil && !isAbortErr(err) {
+		if err != nil && !isAbortedErr(err) {
 			if isSessionNotFoundError(err) {
 				// Discard the bad session.
 				sh.destroy()
@@ -1116,7 +1116,7 @@ func (t *writeOnlyTransaction) applyAtLeastOnce(ctx context.Context, ms ...*Muta
 
 // isAbortedErr returns true if the error indicates that an gRPC call is
 // aborted on the server side.
-func isAbortErr(err error) bool {
+func isAbortedErr(err error) bool {
 	if err == nil {
 		return false
 	}