Update YARD documentation param types and return values

lib/good_job.rb

@@ -30,7 +30,7 @@ module GoodJob
   #   @!scope class
   #   The logger used by GoodJob (default: +Rails.logger+).
   #   Use this to redirect logs to a special location or file.
-  #   @return [Logger]
+  #   @return [Logger, nil]
   #   @example Output GoodJob logs to a file:
   #     GoodJob.logger = ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new("log/my_logs.log"))
   mattr_accessor :logger, default: ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new($stdout))
@@ -42,7 +42,7 @@ module GoodJob
   #   If you want to preserve jobs for latter inspection, set this to +true+.
   #   If you want to preserve only jobs that finished with error for latter inspection, set this to +:on_unhandled_error+.
   #   If +true+, you will need to clean out jobs using the +good_job cleanup_preserved_jobs+ CLI command.
-  #   @return [Boolean]
+  #   @return [Boolean, nil]
   mattr_accessor :preserve_job_records, default: false
 
   # @!attribute [rw] retry_on_unhandled_error
@@ -51,10 +51,11 @@ module GoodJob
   #   If +true+, causes jobs to be re-queued and retried if they raise an instance of +StandardError+.
   #   If +false+, jobs will be discarded or marked as finished if they raise an instance of +StandardError+.
   #   Instances of +Exception+, like +SIGINT+, will *always* be retried, regardless of this attribute's value.
-  #   @return [Boolean]
+  #   @return [Boolean, nil]
   mattr_accessor :retry_on_unhandled_error, default: true
 
   # @deprecated Use {GoodJob#retry_on_unhandled_error} instead.
+  # @return [Boolean, nil]
   def self.reperform_jobs_on_standard_error
     ActiveSupport::Deprecation.warn(
       "Calling 'GoodJob.reperform_jobs_on_standard_error' is deprecated. Please use 'retry_on_unhandled_error'"
@@ -63,6 +64,8 @@ def self.reperform_jobs_on_standard_error
   end
 
   # @deprecated Use {GoodJob#retry_on_unhandled_error=} instead.
+  # @param value [Boolean]
+  # @return [Boolean]
   def self.reperform_jobs_on_standard_error=(value)
     ActiveSupport::Deprecation.warn(
       "Setting 'GoodJob.reperform_jobs_on_standard_error=' is deprecated. Please use 'retry_on_unhandled_error='"
@@ -77,24 +80,25 @@ def self.reperform_jobs_on_standard_error=(value)
   #   @example Send errors to Sentry
   #     # config/initializers/good_job.rb
   #     GoodJob.on_thread_error = -> (exception) { Raven.capture_exception(exception) }
-  #   @return [#call, nil]
+  #   @return [Proc, nil]
   mattr_accessor :on_thread_error, default: nil
 
   # Stop executing jobs.
   # GoodJob does its work in pools of background threads.
   # When forking processes you should shut down these background threads before forking, and restart them after forking.
   # For example, you should use +shutdown+ and +restart+ when using async execution mode with Puma.
   # See the {file:README.md#executing-jobs-async--in-process} for more explanation and examples.
-  # @param wait [Boolean] whether to wait for shutdown
+  # @param timeout [Numeric, nil] Seconds to wait for active threads to finish
+  # @param wait [Boolean, nil] whether to wait for shutdown
   # @return [void]
   def self.shutdown(timeout: -1, wait: nil)
-    timeout = if wait.present?
+    timeout = if wait.nil?
+                timeout
+              else
                 ActiveSupport::Deprecation.warn(
                   "Using `GoodJob.shutdown` with `wait:` kwarg is deprecated; use `timeout:` kwarg instead e.g. GoodJob.shutdown(timeout: #{wait ? '-1' : 'nil'})"
                 )
                 wait ? -1 : nil
-              else
-                timeout
               end
 
     executables = Array(Notifier.instances) + Array(Poller.instances) + Array(Scheduler.instances)
@@ -114,18 +118,21 @@ def self.shutdown?
   # When forking processes you should shut down these background threads before forking, and restart them after forking.
   # For example, you should use +shutdown+ and +restart+ when using async execution mode with Puma.
   # See the {file:README.md#executing-jobs-async--in-process} for more explanation and examples.
+  # @param timeout [Numeric, nil] Seconds to wait for active threads to finish.
   # @return [void]
   def self.restart(timeout: -1)
     executables = Array(Notifier.instances) + Array(Poller.instances) + Array(Scheduler.instances)
     _shutdown_all(executables, :restart, timeout: timeout)
   end
 
   # Sends +#shutdown+ or +#restart+ to executable objects ({GoodJob::Notifier}, {GoodJob::Poller}, {GoodJob::Scheduler})
-  # @param executables [Array<(Notifier, Poller, Scheduler)>] Objects to shut down.
+  # @param executables [Array<Notifier, Poller, Scheduler, MultiScheduler>] Objects to shut down.
   # @param method_name [:symbol] Method to call, e.g. +:shutdown+ or +:restart+.
   # @param timeout [nil,Numeric]
   # @return [void]
   def self._shutdown_all(executables, method_name = :shutdown, timeout: -1)
+    timeout = -1 if timeout.nil?
+
     if timeout.positive?
       executables.each { |executable| executable.send(method_name, timeout: nil) }
 

lib/good_job/adapter.rb

@@ -6,7 +6,7 @@ class Adapter
     # Valid execution modes.
     EXECUTION_MODES = [:async, :async_server, :external, :inline].freeze
 
-    # @param execution_mode [nil, Symbol] specifies how and where jobs should be executed. You can also set this with the environment variable +GOOD_JOB_EXECUTION_MODE+.
+    # @param execution_mode [Symbol, nil] specifies how and where jobs should be executed. You can also set this with the environment variable +GOOD_JOB_EXECUTION_MODE+.
     #
     #  - +:inline+ executes jobs immediately in whatever process queued them (usually the web server process). This should only be used in test and development environments.
     #  - +:external+ causes the adapter to enqueue jobs, but not execute them. When using this option (the default for production environments), you'll need to use the command-line tool to actually execute your jobs.
@@ -19,11 +19,11 @@ class Adapter
     #  - +development+ and +test+: +:inline+
     #  - +production+ and all other environments: +:external+
     #
-    # @param max_threads [nil, Integer] sets the number of threads per scheduler to use when +execution_mode+ is set to +:async+. The +queues+ parameter can specify a number of threads for each group of queues which will override this value. You can also set this with the environment variable +GOOD_JOB_MAX_THREADS+. Defaults to +5+.
-    # @param queues [nil, String] determines which queues to execute jobs from when +execution_mode+ is set to +:async+. See {file:README.md#optimize-queues-threads-and-processes} for more details on the format of this string. You can also set this with the environment variable +GOOD_JOB_QUEUES+. Defaults to +"*"+.
-    # @param poll_interval [nil, Integer] sets the number of seconds between polls for jobs when +execution_mode+ is set to +:async+. You can also set this with the environment variable +GOOD_JOB_POLL_INTERVAL+. Defaults to +1+.
+    # @param max_threads [Integer, nil] sets the number of threads per scheduler to use when +execution_mode+ is set to +:async+. The +queues+ parameter can specify a number of threads for each group of queues which will override this value. You can also set this with the environment variable +GOOD_JOB_MAX_THREADS+. Defaults to +5+.
+    # @param queues [String, nil] determines which queues to execute jobs from when +execution_mode+ is set to +:async+. See {file:README.md#optimize-queues-threads-and-processes} for more details on the format of this string. You can also set this with the environment variable +GOOD_JOB_QUEUES+. Defaults to +"*"+.
+    # @param poll_interval [Integer, nil] sets the number of seconds between polls for jobs when +execution_mode+ is set to +:async+. You can also set this with the environment variable +GOOD_JOB_POLL_INTERVAL+. Defaults to +1+.
     def initialize(execution_mode: nil, queues: nil, max_threads: nil, poll_interval: nil)
-      if caller[0..4].find { |c| c.include?("/config/application.rb") || c.include?("/config/environments/") }
+      if caller[0..4]&.find { |c| c.include?("/config/application.rb") || c.include?("/config/environments/") }
         ActiveSupport::Deprecation.warn(<<~DEPRECATION)
           GoodJob no longer recommends creating a GoodJob::Adapter instance:
 
@@ -70,7 +70,7 @@ def enqueue(active_job)
     # Enqueues an ActiveJob job to be run at a specific time.
     # For use by Rails; you should generally not call this directly.
     # @param active_job [ActiveJob::Base] the job to be enqueued from +#perform_later+
-    # @param timestamp [Integer] the epoch time to perform the job
+    # @param timestamp [Integer, nil] the epoch time to perform the job
     # @return [GoodJob::Job]
     def enqueue_at(active_job, timestamp)
       good_job = GoodJob::Job.enqueue(
@@ -97,22 +97,22 @@ def enqueue_at(active_job, timestamp)
     end
 
     # Shut down the thread pool executors.
-    # @param timeout [nil, Numeric] Seconds to wait for active threads.
+    # @param timeout [nil, Numeric, Symbol] Seconds to wait for active threads.
     #
     #   * +nil+, the scheduler will trigger a shutdown but not wait for it to complete.
     #   * +-1+, the scheduler will wait until the shutdown is complete.
     #   * +0+, the scheduler will immediately shutdown and stop any threads.
     #   * A positive number will wait that many seconds before stopping any remaining active threads.
-    # @param wait [Boolean] Deprecated. Use +timeout:+ instead.
+    # @param wait [Boolean, nil] Deprecated. Use +timeout:+ instead.
     # @return [void]
     def shutdown(timeout: :default, wait: nil)
-      timeout = if wait.present?
+      timeout = if wait.nil?
+                  timeout
+                else
                   ActiveSupport::Deprecation.warn(
                     "Using `GoodJob::Adapter.shutdown` with `wait:` kwarg is deprecated; use `timeout:` kwarg instead e.g. GoodJob::Adapter.shutdown(timeout: #{wait ? '-1' : 'nil'})"
                   )
                   wait ? -1 : nil
-                else
-                  timeout
                 end
 
       timeout = if timeout == :default
@@ -126,25 +126,29 @@ def shutdown(timeout: :default, wait: nil)
     end
 
     # Whether in +:async+ execution mode.
+    # @return [Boolean]
     def execute_async?
       @configuration.execution_mode == :async ||
         @configuration.execution_mode == :async_server && in_server_process?
     end
 
     # Whether in +:external+ execution mode.
+    # @return [Boolean]
     def execute_externally?
       @configuration.execution_mode == :external ||
         @configuration.execution_mode == :async_server && !in_server_process?
     end
 
     # Whether in +:inline+ execution mode.
+    # @return [Boolean]
     def execute_inline?
       @configuration.execution_mode == :inline
     end
 
     private
 
     # Whether running in a web server process.
+    # @return [Boolean, nil]
     def in_server_process?
       return @_in_server_process if defined? @_in_server_process
 

lib/good_job/configuration.rb

@@ -84,9 +84,9 @@ def max_threads
     # on the format of this string.
     # @return [String]
     def queue_string
-      options[:queues] ||
-        rails_config[:queues] ||
-        env['GOOD_JOB_QUEUES'] ||
+      options[:queues].presence ||
+        rails_config[:queues].presence ||
+        env['GOOD_JOB_QUEUES'].presence ||
         '*'
     end
 

lib/good_job/current_execution.rb

@@ -3,7 +3,6 @@
 module GoodJob
   # Thread-local attributes for passing values from Instrumentation.
   # (Cannot use ActiveSupport::CurrentAttributes because ActiveJob resets it)
-
   module CurrentExecution
     # @!attribute [rw] error_on_retry
     #   @!scope class

lib/good_job/daemon.rb

@@ -13,6 +13,7 @@ def initialize(pidfile:)
     end
 
     # Daemonizes the current process and writes out a pidfile.
+    # @return [void]
     def daemonize
       check_pid
       Process.daemon
@@ -21,6 +22,7 @@ def daemonize
 
     private
 
+    # @return [void]
     def write_pid
       File.open(pidfile, ::File::CREAT | ::File::EXCL | ::File::WRONLY) { |f| f.write(Process.pid.to_s) }
       at_exit { File.delete(pidfile) if File.exist?(pidfile) }
@@ -29,10 +31,12 @@ def write_pid
       retry
     end
 
+    # @return [void]
     def delete_pid
       File.delete(pidfile) if File.exist?(pidfile)
     end
 
+    # @return [void]
     def check_pid
       case pid_status(pidfile)
       when :running, :not_owned
@@ -42,6 +46,8 @@ def check_pid
       end
     end
 
+    # @param pidfile [Pathname, String]
+    # @return [Symbol]
     def pid_status(pidfile)
       return :exited unless File.exist?(pidfile)
 

lib/good_job/job.rb

@@ -234,7 +234,7 @@ def executable?
 
     private
 
-    # @return [GoodJob::ExecutionResult]
+    # @return [ExecutionResult]
     def execute
       params = serialized_params.merge(
         "provider_job_id" => id

lib/good_job/job_performer.rb

@@ -24,7 +24,7 @@ def name
     end
 
     # Perform the next eligible job
-    # @return [nil, Object] Returns job result or +nil+ if no job was found
+    # @return [Object, nil] Returns job result or +nil+ if no job was found
     def next
       job_query.perform_with_advisory_lock
     end
@@ -54,7 +54,7 @@ def next?(state = {})
     # @param after [DateTime, Time, nil] future jobs scheduled after this time
     # @param limit [Integer] number of future timestamps to return
     # @param now_limit [Integer] number of past timestamps to return
-    # @return [Array<(Time, DateTime)>, nil]
+    # @return [Array(Time, DateTime), nil]
     def next_at(after: nil, limit: nil, now_limit: nil)
       job_query.next_scheduled_at(after: after, limit: limit, now_limit: now_limit)
     end

lib/good_job/lockable.rb

@@ -245,11 +245,8 @@ def advisory_unlock!
 
     private
 
-    def sanitize_sql_for_conditions(*args)
-      # Made public in Rails 5.2
-      self.class.send(:sanitize_sql_for_conditions, *args)
-    end
-
+    # @param query [String]
+    # @return [Boolean]
     def pg_or_jdbc_query(query)
       if Concurrent.on_jruby?
         # Replace $1 bind parameters with ?