From 3412c8946272cc69ebf1abbc78a5c0b5e35c1d7d Mon Sep 17 00:00:00 2001
From: Nick Elser <nick.elser@gmail.com>
Date: Fri, 9 Sep 2016 18:11:59 -0700
Subject: [PATCH] Add more detailed documentation/comments.

---
 CHANGELOG.md         |  4 ++++
 lib/caddy.rb         | 20 ++++++++++++++++----
 lib/caddy/cache.rb   | 20 ++++++++++++++++++++
 lib/caddy/version.rb |  2 +-
 4 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a146819..8fb3082 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.5.5
+
+- Add more detailed documentation/comments.
+
 ## 1.5.4
 
 - Some minor wording updates.
diff --git a/lib/caddy.rb b/lib/caddy.rb
index 6c8c769..73cea55 100644
--- a/lib/caddy.rb
+++ b/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
diff --git a/lib/caddy/cache.rb b/lib/caddy/cache.rb
index 6fabd8c..6b43325 100644
--- a/lib/caddy/cache.rb
+++ b/lib/caddy/cache.rb
@@ -6,6 +6,8 @@ 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
@@ -13,10 +15,17 @@ def initialize(key)
       @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
@@ -24,6 +33,13 @@ def 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
diff --git a/lib/caddy/version.rb b/lib/caddy/version.rb
index fbf1632..daf1455 100644
--- a/lib/caddy/version.rb
+++ b/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