chore: fix the flaky list_backups test

Author: viacheslav-rostovtsev

google-cloud-spanner/acceptance/spanner/backup_operations_test.rb

@@ -34,14 +34,14 @@
     create_job = database.create_backup backup_id, expire_time
     create_job.wait_until_done!
 
-    # All
+    # @type [::Array<Google::Cloud::Spanner::Backup::Job>]
     jobs = instance.backup_operations.all.to_a
     _(jobs).wont_be :empty?
 
     jobs.each do |job|
       _(job).must_be_kind_of Google::Cloud::Spanner::Backup::Job
 
-      unless job.error?
+      if job.done?
         _(job.backup).must_be_kind_of Google::Cloud::Spanner::Backup
       end
 

google-cloud-spanner/lib/google/cloud/spanner/backup/job.rb

@@ -58,12 +58,14 @@ class Backup
         #   end
         #
         class Job
-          ##
-          # @private The `Gapic::Operation` gRPC object.
+          # The wrapped `Gapic::Operation` object.
+          # @private
+          # @return [::Gapic::Operation]
           attr_accessor :grpc
 
-          ##
-          # @private The gRPC Service object.
+          # The `Spanner::Service` reference.
+          # @private
+          # @return [::Google::Cloud::Spanner::Service]
           attr_accessor :service
 
           ##
@@ -265,8 +267,11 @@ def cancel_time
             Convert.timestamp_to_time @grpc.metadata.cancel_time
           end
 
-          ##
-          # @private New Backup::Job from a `Gapic::Operation` object.
+          # Create a new Backup::Job from a `Gapic::Operation` object.
+          # @param grpc [::Gapic::Operation`] The wrapped `Gapic::Operation` object.
+          # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+          # @private
+          # @return [::Google::Cloud::Spanner::Backup::Job]
           def self.from_grpc grpc, service
             new.tap do |job|
               job.instance_variable_set :@grpc, grpc

google-cloud-spanner/lib/google/cloud/spanner/backup/job/list.rb

@@ -33,8 +33,9 @@ class Job
           #   {Google::Cloud::Spanner::Admin::Database.database_admin}.list_backup_operations instead.
           #
           class List < DelegateClass(::Array)
+            # The `Spanner::Service` reference.
             # @private
-            # The gRPC Service object.
+            # @return [::Google::Cloud::Spanner::Service]
             attr_accessor :service
 
             # @private
@@ -148,13 +149,14 @@ def all &block
               end
             end
 
-            ##
-            # @private
-            #
-            # New Backup::Job::List from a
+            # Creates a new `Spanner::Backup::Job::List` of `Gapic::Operation` operations from a
             # `Gapic::PagedEnumerable<Google::Longrunning::Operation>`
             # object. Operation object is a backup operation.
-            #
+            # @param grpc [::Gapic::PagedEnumerable<::Google::Longrunning::Operation>] 
+            #   Wrapped `Gapic::PagedEnumberable` reference.
+            # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+            # @private
+            # @return [::Google::Cloud::Spanner::Backup::Job::List] 
             def self.from_grpc grpc, service
               operations_client =
                 service.databases.instance_variable_get "@operations_client"

google-cloud-spanner/lib/google/cloud/spanner/client.rb

@@ -2128,13 +2128,15 @@ def transaction deadline: 120, exclude_txn_from_change_streams: false,
               yield tx
               transaction_id = nil
               transaction_id = tx.transaction_id if tx.existing_transaction?
-              commit_resp = @project.service.commit \
-                tx.session.path, tx.mutations,
+              commit_resp = @project.service.commit(
+                tx.session.path,
+                tx.mutations,
                 transaction_id: transaction_id,
                 exclude_txn_from_change_streams: exclude_txn_from_change_streams,
                 commit_options: commit_options,
                 request_options: request_options,
                 call_options: call_options
+              )
               resp = CommitResponse.from_grpc commit_resp
               commit_options ? resp : resp.timestamp
             rescue GRPC::Aborted,

google-cloud-spanner/lib/google/cloud/spanner/instance.rb

@@ -74,11 +74,15 @@ module Spanner
       #   end
       #
       class Instance
-        ##
-        # @private The gRPC Service object.
+        # The `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
         attr_accessor :service
 
-        # @private Creates a new Instance instance.
+        # Creates a new `Spanner::Instance` instance.
+        # @param grpc [::Google::Cloud::Spanner::Admin::Instance::V1::Instance] The protobuf `V1::Instance` underlying object.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @private
         def initialize grpc, service
           @grpc = grpc
           @service = service
@@ -957,9 +961,12 @@ def test_permissions *permissions
           grpc.permissions
         end
 
-        ##
-        # @private Creates a new Instance instance from a
+        # Creates a new Instance instance from a
         # `Google::Cloud::Spanner::Admin::Instance::V1::Instance`.
+        # @param grpc [::Google::Cloud::Spanner::Admin::Instance::V1::Instance] The protobuf `V1::Instance` underlying object.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Instance]
         def self.from_grpc grpc, service
           new grpc, service
         end

google-cloud-spanner/lib/google/cloud/spanner/service.rb

@@ -157,6 +157,11 @@ def list_instances token: nil, max: nil, call_options: nil
           paged_enum.response
         end
 
+        # Gets information about a particular instance
+        # @param name [::String] The name of the Spanner instance, e.g. 'myinstance'
+        #   or path to the Spanner instance, e.g. `projects/myproject/instances/myinstance`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Admin::Instance::V1::Instance]
         def get_instance name, call_options: nil
           opts = default_options call_options: call_options
           request = { name: instance_path(name) }
@@ -525,8 +530,8 @@ def partition_query session_name, sql, transaction, params: nil,
         #   Example option: `:priority`.
         # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
         #   call options. Example option `:timeout`.
-        # @return [::Google::Cloud::Spanner::V1::CommitResponse]
         # @private
+        # @return [::Google::Cloud::Spanner::V1::CommitResponse]
         def commit session_name, mutations = [],
                    transaction_id: nil, exclude_txn_from_change_streams: false,
                    commit_options: nil, request_options: nil, call_options: nil
@@ -717,6 +722,25 @@ def list_database_operations instance_id,
           databases.list_database_operations request, opts
         end
 
+        # Lists the backup `::Google::Longrunning::Operation` long-running operations in
+        # the given instance. A backup operation has a name of the form
+        # projects/<project>/instances/<instance>/backups/<backup>/operations/<operation>.
+        # @param instance_id [::String] The name of the Spanner instance, e.g. 'myinstance'
+        #   or path to the Spanner instance, e.g. `projects/myproject/instances/myinstance`.
+        # @param filter [::String, nil] Optional.
+        #   An expression that filters the list of returned backup operations.
+        #   Example filter: `done:true`.
+        # @param page_size [::Integer, nil] Optional.
+        #   Number of operations to be returned in the response. If 0 or
+        #   less, defaults to the server's maximum allowed page size.
+        # @param page_token [::String, nil] Optional.
+        #   If set, `page_token` should contain a value received as a `next_page_token`
+        #   from a previous `ListBackupOperationsResponse` to the same `parent`
+        #   and with the same `filter`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @private
+        # @return [::Gapic::PagedEnumerable<::Gapic::Operation>]
         def list_backup_operations instance_id,
                                    filter: nil, page_size: nil,
                                    page_token: nil,
@@ -806,6 +830,12 @@ def project_path
             project: project
         end
 
+        # Converts an instance name to instance path.
+        # If an instance path is given, returns it unchanged
+        # @param name [::String] name of the Spanner instance, e.g. 'myinstance'
+        #   or path to the Spanner instance, e.g. `projects/myproject/instances/myinstance`.
+        # @private
+        # @return [::String]
         def instance_path name
           return name if name.to_s.include? "/"