chore: document some private methods and add multiplex plumbing (#184)

viacheslav-rostovtsev · web-flow · commit 999ddb1b6d21 · 2025-09-24T13:10:49.000-07:00
diff --git a/google-cloud-spanner/.rubocop.yml b/google-cloud-spanner/.rubocop.yml
@@ -11,7 +11,7 @@ AllCops:
     - "vendor/**/*"
     - "acceptance/data/protos/**/*"
 
-Documentation:
+Style/Documentation:
   Enabled: false
 
 Metrics/BlockLength:
diff --git a/google-cloud-spanner/Gemfile b/google-cloud-spanner/Gemfile
@@ -19,5 +19,6 @@ gem "minitest-rg", "~> 5.3"
 gem "rake"
 gem "redcarpet", "~> 3.0"
 gem "simplecov", "~> 0.22"
+gem "solargraph", group: :development, require: false
 gem "yard", "~> 0.9"
-gem "yard-doctest", "~> 0.1.17"
+gem "yard-doctest", "~> 0.1.17", group: :development
diff --git a/google-cloud-spanner/acceptance/spanner/backup_operations_test.rb b/google-cloud-spanner/acceptance/spanner/backup_operations_test.rb
@@ -24,6 +24,7 @@
   it "list backup operations" do
     skip if emulator_enabled?
 
+    # @type [::Google::Cloud::Spanner::Instance]
     instance = spanner.instance instance_id
     _(instance).wont_be :nil?
 
@@ -33,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.error?
         _(job.backup).must_be_kind_of Google::Cloud::Spanner::Backup
       end
 
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/backup/job.rb b/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
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/backup/job/list.rb b/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"
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/batch_client.rb b/google-cloud-spanner/lib/google/cloud/spanner/batch_client.rb
@@ -63,8 +63,18 @@ module Spanner
       #     new_partition
       #
       class BatchClient
-        ##
-        # @private Creates a new Spanner BatchClient instance.
+        # Creates a new Spanner BatchClient instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @param database_id [::String] Database id, e.g. `"my-database"`.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example parameter `:optimizer_version`.
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
         def initialize project, instance_id, database_id, session_labels: nil,
                        query_options: nil, directed_read_options: nil
           @project = project
@@ -404,15 +414,18 @@ def inspect
 
         protected
 
-        ##
-        # @private Raise an error unless an active connection to the service is
+        # Raise an error unless an active connection to the service is
         # available.
+        # @private
+        # @raise [StandardError]
+        # @return [nil]
         def ensure_service!
           raise "Must have active connection to service" unless @project.service
         end
 
-        ##
         # New session for each use.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
         def session
           ensure_service!
           grpc = @project.service.create_session \
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/client.rb b/google-cloud-spanner/lib/google/cloud/spanner/client.rb
@@ -51,12 +51,26 @@ module Spanner
       #   end
       #
       class Client
-        ##
+        # A semi-arbitrary constant for thread-wide global parameter name
         # @private
         IS_TRANSACTION_RUNNING_KEY = "ruby_spanner_is_transaction_running".freeze
 
-        ##
-        # @private Creates a new Spanner Client instance.
+        # Creates a new Spanner Client instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @param database_id [::String] Database id, e.g. `"my-database"`.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param pool_opts [::Hash] Optional. `Spanner::Pool` creation options.
+        #   Example parameter: `:keepalive`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example parameter `:optimizer_version`.
+        # @param database_role [::String, nil] Optional. The Spanner session creator role.
+        #   Example: `analyst`
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
         def initialize project, instance_id, database_id, session_labels: nil,
                        pool_opts: {}, query_options: nil, database_role: nil,
                        directed_read_options: nil
@@ -89,7 +103,7 @@ def database_id
         end
 
         # The Spanner project connected to.
-        # @return [Project]
+        # @return [::Google::Cloud::Spanner::Project]
         def project
           @project
         end
@@ -2114,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,
@@ -2419,17 +2435,21 @@ def reset
           @pool.reset
         end
 
-        ##
+        # Creates a new Session objece.
+        # @param multiplexed [::Boolean] Optional. Default to `false`.
+        #   If `true`, specifies a multiplexed session.
         # @private
-        # Creates a new session object every time.
-        def create_new_session
+        # @return [::Google::Cloud::Spanner::Session]
+        def create_new_session multiplexed: false
           ensure_service!
           grpc = @project.service.create_session \
             Admin::Database::V1::DatabaseAdmin::Paths.database_path(
               project: project_id, instance: instance_id, database: database_id
             ),
             labels: @session_labels,
-            database_role: @database_role
+            database_role: @database_role,
+            multiplexed: multiplexed
+
           Session.from_grpc grpc, @project.service, query_options: @query_options
         end
 
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/instance.rb b/google-cloud-spanner/lib/google/cloud/spanner/instance.rb
@@ -74,11 +74,16 @@ 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 +962,13 @@ 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
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/pool.rb b/google-cloud-spanner/lib/google/cloud/spanner/pool.rb
@@ -36,6 +36,16 @@ class Pool
         # and `Session` objects as values.
         attr_accessor :sessions_in_use
 
+        # Creates a new Session pool that manages non-multiplexed sessions.
+        # @param client [::Google::Cloud::Spanner::Client] A `Spanner::Client` reference
+        # @param min [::Integer] Min number of sessions to keep
+        # @param max [::Integer] Max number of sessions to keep
+        # @param keepalive [::Numeric] How long after their last usage the sessions can be reclaimed
+        # @param fail [::Boolean] If `true` the pool will raise `SessionLimitError` if number of new sessions
+        #   needed is more that can be created due to the `max` parameter. If `false` it will wait instead.
+        # @param threads [::Integer, nil] Number of threads in the thread pool that is used for keepalive and
+        #   release session actions. If `nil` the Pool will choose a reasonable default.
+        # @private
         def initialize client, min: 10, max: 100, keepalive: 1800,
                        fail: true, threads: nil
           @client = client
@@ -52,6 +62,11 @@ def initialize client, min: 10, max: 100, keepalive: 1800,
           init
         end
 
+        # Provides a session for running an operation
+        # @yield session Session a client can use to run an operation
+        # @yieldparam [::Google::Cloud::Spanner::Session] `Spanner::Session` to run an operation
+        # @private
+        # @return [nil]
         def with_session
           session = checkout_session
           begin
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/project.rb b/google-cloud-spanner/lib/google/cloud/spanner/project.rb
@@ -66,12 +66,22 @@ module Spanner
       #   end
       #
       class Project
-        ##
-        # @private The Service object.
-        attr_accessor :service, :query_options
+        # The `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
+        attr_accessor :service
 
-        ##
-        # @private Creates a new Spanner Project instance.
+        # A hash of values to specify the custom query options for executing SQL query.
+        # Example option: `:optimizer_version`.
+        # @private
+        # @return [::Hash, nil]
+        attr_accessor :query_options
+
+        # Creates a new Spanner Project instance.
+        # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` ref.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example option: `:optimizer_version`.
+        # @private
         def initialize service, query_options: nil
           @service = service
           @query_options = query_options
@@ -80,6 +90,8 @@ def initialize service, query_options: nil
         ##
         # The identifier for the Cloud Spanner project.
         #
+        # @return [::String]
+        #
         # @example
         #   require "google/cloud"
         #
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/service.rb b/google-cloud-spanner/lib/google/cloud/spanner/service.rb
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/session.rb b/google-cloud-spanner/lib/google/cloud/spanner/session.rb
diff --git a/google-cloud-spanner/lib/google/cloud/spanner/transaction.rb b/google-cloud-spanner/lib/google/cloud/spanner/transaction.rb
