Documentation - add version info, misc fixes [ci skip] (#2368)

docs/signals.md

@@ -38,10 +38,10 @@ Puma cluster responds to these signals:
 - `TERM` send `TERM` to worker. Worker will attempt to finish then exit.
 - `USR2` restart workers. This also reloads puma configuration file, if there is one.
 - `USR1` restart workers in phases, a rolling restart. This will not reload configuration file.
-- `HUP`  reopen log files defined in stdout_redirect configuration parameter. If there is no stdout_redirect option provided it will behave like `INT`
-- `INT` equivalent of sending Ctrl-C to cluster. Will attempt to finish then exit.
+- `HUP ` reopen log files defined in stdout_redirect configuration parameter. If there is no stdout_redirect option provided it will behave like `INT`
+- `INT ` equivalent of sending Ctrl-C to cluster. Will attempt to finish then exit.
 - `CHLD`
-- `URG` refork workers in phases from worker 0, if `fork_workers` option is enabled.
+- `URG ` refork workers in phases from worker 0, if `fork_workers` option is enabled.
 
 ## Callbacks order in case of different signals
 

ext/puma_http11/mini_ssl.c

@@ -463,6 +463,9 @@ VALUE engine_peercert(VALUE self) {
   return rb_cert_buf;
 }
 
+/* @see Puma::MiniSSL::Socket#ssl_version_state
+ * @version 5.0.0
+ */
 static VALUE
 engine_ssl_vers_st(VALUE self) {
   ms_conn* conn;

lib/puma.rb

@@ -27,6 +27,7 @@ def self.stats
     @get_stats.stats.to_json
   end
 
+  # @version 5.0.0
   def self.stats_hash
     @get_stats.stats
   end

lib/puma/binder.rb

@@ -50,7 +50,12 @@ def initialize(events, conf = Configuration.new)
       @ios = []
     end
 
-    attr_reader :ios, :listeners, :unix_paths, :proto_env, :envs, :activated_sockets, :inherited_fds
+    attr_reader :ios
+
+    # @version 5.0.0
+    attr_reader :activated_sockets, :envs, :inherited_fds, :listeners, :proto_env, , :unix_paths
+
+    # @version 5.0.0
     attr_writer :ios, :listeners
 
     def env(sock)
@@ -61,10 +66,12 @@ def close
       @ios.each { |i| i.close }
     end
 
+    # @version 5.0.0
     def connected_ports
       ios.map { |io| io.addr[1] }.uniq
     end
 
+    # @version 5.0.0
     def create_inherited_fds(env_hash)
       env_hash.select {|k,v| k =~ /PUMA_INHERIT_\d+/}.each do |_k, v|
         fd, url = v.split(":", 2)
@@ -75,7 +82,9 @@ def create_inherited_fds(env_hash)
     # systemd socket activation.
     # LISTEN_FDS = number of listening sockets. e.g. 2 means accept on 2 sockets w/descriptors 3 and 4.
     # LISTEN_PID = PID of the service process, aka us
-    # see https://www.freedesktop.org/software/systemd/man/systemd-socket-activate.html
+    # @see https://www.freedesktop.org/software/systemd/man/systemd-socket-activate.html
+    # @version 5.0.0
+    #
     def create_activated_fds(env_hash)
       return [] unless env_hash['LISTEN_FDS'] && env_hash['LISTEN_PID'].to_i == $$
       env_hash['LISTEN_FDS'].to_i.times do |index|
@@ -373,6 +382,7 @@ def redirects_for_restart
       redirects
     end
 
+    # @version 5.0.0
     def redirects_for_restart_env
       listeners.each_with_object({}).with_index do |(listen, memo), i|
         memo["PUMA_INHERIT_#{i}"] = "#{listen[1].to_i}:#{listen[0]}"
@@ -387,6 +397,7 @@ def loopback_addresses
       end.map { |addrinfo| addrinfo.ip_address }.uniq
     end
 
+    # @version 5.0.0
     def socket_activation_fd(int)
       int + 3 # 3 is the magic number you add to follow the SA protocol
     end

lib/puma/client.rb

@@ -280,6 +280,8 @@ def peerip
 
     # Returns true if the persistent connection can be closed immediately
     # without waiting for the configured idle/shutdown timeout.
+    # @version 5.0.0
+    #
     def can_close?
       # Allow connection to close if it's received at least one full request
       # and hasn't received any data for a future request.
@@ -443,6 +445,7 @@ def setup_chunked_body(body)
       end
     end
 
+    # @version 5.0.0
     def write_chunk(str)
       @chunked_content_length += @body.write(str)
     end

lib/puma/cluster.rb

@@ -77,6 +77,8 @@ def initialize(idx, pid, phase, options)
       end
 
       attr_reader :index, :pid, :phase, :signal, :last_checkin, :last_status, :started_at
+
+      # @version 5.0.0
       attr_writer :pid, :phase
 
       def booted?
@@ -98,6 +100,8 @@ def ping!(status)
         @last_status = JSON.parse(status, symbolize_names: true)
       end
 
+      # @see Puma::Cluster#check_workers
+      # @version 5.0.0
       def ping_timeout
         @last_checkin +
           (booted? ?
@@ -160,6 +164,7 @@ def spawn_workers
       end
     end
 
+    # @version 5.0.0
     def spawn_worker(idx, master)
       @launcher.config.run_hooks :before_worker_fork, idx, @launcher.events
 
@@ -419,6 +424,7 @@ def preload?
       @options[:preload_app]
     end
 
+    # @version 5.0.0
     def fork_worker!
       if (worker = @workers.find { |w| w.index == 0 })
         worker.phase += 1
@@ -640,6 +646,7 @@ def wait_workers
       end
     end
 
+    # @version 5.0.0
     def timeout_workers
       @workers.each do |w|
         if !w.term? && w.ping_timeout <= Time.now
@@ -649,6 +656,7 @@ def timeout_workers
       end
     end
 
+    # @version 5.0.0
     def nakayoshi_gc
       return unless @options[:nakayoshi_fork]
       log "! Promoting existing objects to old generation..."

lib/puma/configuration.rb

@@ -173,6 +173,7 @@ def flatten!
       self
     end
 
+    # @version 5.0.0
     def default_max_threads
       Puma.mri? ? 5 : 16
     end

lib/puma/control_cli.rb

@@ -12,6 +12,8 @@ module Puma
   class ControlCLI
 
     COMMANDS = %w{halt restart phased-restart start stats status stop reload-worker-directory gc gc-stats thread-backtraces refork}
+
+    # @version 5.0.0
     PRINTABLE_COMMANDS = %w{gc-stats stats thread-backtraces}
 
     def initialize(argv, stdout=STDOUT, stderr=STDERR)

lib/puma/detect.rb

@@ -20,10 +20,12 @@ def self.windows?
     IS_WINDOWS
   end
 
+  # @version 5.0.0
   def self.mri?
     RUBY_ENGINE == 'ruby' || RUBY_ENGINE.nil?
   end
 
+  # @version 5.0.0
   def self.forkable?
     ::Process.respond_to?(:fork)
   end