Add more detailed documentation/comments.

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.5.5
+
+- Add more detailed documentation/comments.
+
 ## 1.5.4
 
 - Some minor wording updates.

lib/caddy.rb

@@ -13,14 +13,22 @@ class << self
   @started_pid = nil
   @caches = Hash.new { |h, k| h[k] = Caddy::Cache.new(k) }
 
+  ##
+  # Returns the cache object for key +k+.
+  #
+  # If the cache at +k+ does not exist yet, Caddy will initialize an empty one.
   def self.[](k)
     @caches[k]
   end
 
-  def self.caches
-    @caches
-  end
-
+  ##
+  # Starts the Caddy refresh processes for all caches.
+  #
+  # If the refresh process was started pre-fork, Caddy will error out, as this means
+  # the refresh process would have been killed by the fork.
+  #
+  # Caddy freezes the hash of caches at this point, so no more further caches can be
+  # added after start.
   def self.start
     if !@started_pid
       @started_pid = $$
@@ -33,10 +41,14 @@ def self.start
     @caches.values.each(&:start).all?
   end
 
+  ##
+  # Cleanly shut down all currently running refreshers.
   def self.stop
     @caches.values.each(&:stop).all?
   end
 
+  ##
+  # Start and then stop again all refreshers. Useful for triggering an immediate refresh of all caches.
   def self.restart
     stop
     start

lib/caddy/cache.rb

@@ -6,24 +6,40 @@ class Cache
 
     attr_accessor :refresher, :refresh_interval, :error_handler
 
+    ##
+    # Create a new cache with key +key+.
     def initialize(key)
       @task = nil
       @refresh_interval = DEFAULT_REFRESH_INTERVAL
       @cache = nil
       @key = key
     end
 
+    ##
+    # Convenience method for getting the value of the refresher-returned object at path +k+,
+    # assuming the refresher-returned value responds to <tt>[]</tt>.
+    #
+    # If not, #cache can be used instead to access the refresher-returned object.
     def [](k)
       cache[k]
     end
 
+    ##
+    # Returns the refresher-produced value that is used as the cache.
     def cache
       raise "Please run `Caddy.start` before attempting to access the cache" unless @task && @task.running?
       raise "Caddy cache access of :#{@key} before initial load; allow some more time for your app to start up" unless @cache
 
       @cache
     end
 
+    ##
+    # Starts the period refresh cycle.
+    #
+    # Every +refresh_interval+ seconds -- smoothed by a jitter amount (a random amount +/- +REFRESH_INTERVAL_JITTER_PCT+) --
+    # the refresher lambda is called and the results stored in +cache+.
+    #
+    # Note that the result of the refresh is frozen to avoid multithreading mutations.
     def start
       unless refresher && refresher.respond_to?(:call)
         raise "Please set your cache refresher via `Caddy[:#{@key}].refresher = -> { <code that returns a value> }`"
@@ -52,6 +68,10 @@ def start
       @task.running?
     end
 
+    ##
+    # Stops the current executing refresher.
+    #
+    # The current cache value is persisted even if the task is stopped.
     def stop
       @task.shutdown if @task && @task.running?
     end

lib/caddy/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Caddy
-  VERSION = "1.5.4".freeze
+  VERSION = "1.5.5".freeze
 end