cachetastic 1.1.3 → 1.1.8

data/doc/fr_method_index.html

@@ -20,53 +20,52 @@
 <div id="index">
   <h1 class="section-bar">Methods</h1>
   <div id="index-entries">
-    <a href="classes/Cachetastic/Caches/Base.html#M000033">all_registered_caches (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Helpers/ActiveRecord.html#M000007">cache (Cachetastic::Helpers::ActiveRecord)</a><br />
-    <a href="classes/Cachetastic/Helpers/ActiveRecord.html#M000006">cache_class (Cachetastic::Helpers::ActiveRecord)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000041">cache_name (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000032">all_registered_caches (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000039">cache_name (Cachetastic::Caches::Base)</a><br />
     <a href="classes/ActiveRecord/Base.html#M000004">cache_self (ActiveRecord::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Base.html#M000031">configure (Cachetastic::Stores::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Base.html#M000030">debug? (Cachetastic::Stores::Base)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000037">delete (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000025">delete (Cachetastic::Stores::LocalMemory)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000011">delete (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000042">calculate_expiry_time (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/Base.html#M000024">debug? (Cachetastic::Stores::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000022">delete (Cachetastic::Stores::LocalMemory)</a><br />
+    <a href="classes/Cachetastic/Stores/File.html#M000031">delete (Cachetastic::Stores::File)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000035">delete (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000008">delete (Cachetastic::Stores::Memcache)</a><br />
     <a href="classes/ActiveRecord/Base.html#M000002">delete_from_cache (ActiveRecord::Base)</a><br />
-    <a href="classes/Cachetastic/Helpers/ActiveRecord.html#M000008">expire_all (Cachetastic::Helpers::ActiveRecord)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000038">expire_all (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000022">expire_all (Cachetastic::Stores::LocalMemory)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000013">expire_all (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Connection.html#M000046">get (Cachetastic::Connection)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000012">get (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000023">get (Cachetastic::Stores::LocalMemory)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000035">get (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000010">expire_all (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000019">expire_all (Cachetastic::Stores::LocalMemory)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000036">expire_all (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/File.html#M000028">expire_all (Cachetastic::Stores::File)</a><br />
+    <a href="classes/Cachetastic/Stores/File.html#M000029">get (Cachetastic::Stores::File)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000009">get (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Connection.html#M000045">get (Cachetastic::Connection)</a><br />
+    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000020">get (Cachetastic::Stores::LocalMemory)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000033">get (Cachetastic::Caches::Base)</a><br />
     <a href="classes/ActiveRecord/Base.html#M000001">get_from_cache (ActiveRecord::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Base.html#M000032">get_options (Cachetastic::Stores::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000019">get_version (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000018">increment_version (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000034">inherited (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000014">inspect (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000043">logger (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000015">namespace (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Stores/Base.html#M000028">new (Cachetastic::Stores::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory/StoreObject.html#M000026">new (Cachetastic::Stores::LocalMemory::StoreObject)</a><br />
-    <a href="classes/Cachetastic/Caches/Base/RegisteredCaches.html#M000044">new (Cachetastic::Caches::Base::RegisteredCaches)</a><br />
-    <a href="classes/Cachetastic/Connection.html#M000045">new (Cachetastic::Connection)</a><br />
-    <a href="classes/Cachetastic/Logger.html#M000047">new (Cachetastic::Logger)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000017">ns_versions (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000039">populate_all (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000010">set (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000036">set (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000024">set (Cachetastic::Stores::LocalMemory)</a><br />
+    <a href="classes/Cachetastic/Stores/Base.html#M000025">get_options (Cachetastic::Stores::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000016">get_version (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000015">increment_version (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000011">inspect (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000041">logger (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000013">namespace (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Stores/Base.html#M000023">new (Cachetastic::Stores::Base)</a><br />
+    <a href="classes/Cachetastic/Connection.html#M000044">new (Cachetastic::Connection)</a><br />
+    <a href="classes/Cachetastic/Caches/Base/RegisteredCaches.html#M000043">new (Cachetastic::Caches::Base::RegisteredCaches)</a><br />
+    <a href="classes/Cachetastic/Logger.html#M000046">new (Cachetastic::Logger)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000014">ns_versions (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000037">populate_all (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000034">set (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000021">set (Cachetastic::Stores::LocalMemory)</a><br />
+    <a href="classes/Cachetastic/Stores/File.html#M000030">set (Cachetastic::Stores::File)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000007">set (Cachetastic::Stores::Memcache)</a><br />
     <a href="classes/ActiveRecord/Base.html#M000003">set_into_cache (ActiveRecord::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000021">setup (Cachetastic::Stores::LocalMemory)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000009">setup (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory/StoreObject.html#M000027">size (Cachetastic::Stores::LocalMemory::StoreObject)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000040">stats (Cachetastic::Caches::Base)</a><br />
-    <a href="classes/Cachetastic/Caches/Base.html#M000042">store (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/File.html#M000027">setup (Cachetastic::Stores::File)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000006">setup (Cachetastic::Stores::Memcache)</a><br />
+    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000018">setup (Cachetastic::Stores::LocalMemory)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000038">stats (Cachetastic::Caches::Base)</a><br />
+    <a href="classes/Cachetastic/Caches/Base.html#M000040">store (Cachetastic::Caches::Base)</a><br />
     <a href="classes/ActiveRecord/Base.html#M000005">uncache_self (ActiveRecord::Base)</a><br />
-    <a href="classes/Cachetastic/Stores/Memcache.html#M000016">valid? (Cachetastic::Stores::Memcache)</a><br />
-    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000020">valid? (Cachetastic::Stores::LocalMemory)</a><br />
-    <a href="classes/Cachetastic/Stores/Base.html#M000029">valid? (Cachetastic::Stores::Base)</a><br />
+    <a href="classes/Cachetastic/Stores/File.html#M000026">valid? (Cachetastic::Stores::File)</a><br />
+    <a href="classes/Cachetastic/Stores/LocalMemory.html#M000017">valid? (Cachetastic::Stores::LocalMemory)</a><br />
+    <a href="classes/Cachetastic/Stores/Memcache.html#M000012">valid? (Cachetastic::Stores::Memcache)</a><br />
   </div>
 </div>
 </body>

data/doc/index.html

@@ -5,12 +5,12 @@
 
 <!--
 
-    RDoc Documentation
+    Cachetastic-RDoc
 
   -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
-  <title>RDoc Documentation</title>
+  <title>Cachetastic-RDoc</title>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
 </head>
 <frameset rows="20%, 80%">

data/init.rb

@@ -0,0 +1 @@
+# :include: README

data/lib/caches/cachetastic_caches_base.rb

@@ -1,9 +1,37 @@
 require 'singleton'
+# When creating a new 'Cache' this class should be extended.
+# Once extended you'll only need to override just the methods
+# that are different for your cache.
+#   class MyAwesomeCache < Cachetastic::Caches::Base
+#   end
+#   MyAwesomeCache.set(1, "One")
+#   MyAwesomeCache.get(1) # => "One"
+#   MyAwesomeCache.update(1, "One!!")
+#   MyAwesomeCache.get(1) # => "One!!"
+#   MyAwesomeCache.delete(1)
+#   MyAwesomeCache.get(1) # => nil
+# 
+#   class MyAwesomeCache < Cachetastic::Caches::Base
+#     class << self
+#       def get(key)
+#         super(key) do
+#           set(key, key * 10)
+#         end
+#       end
+#     end
+#   end
+#   MyAwesomeCache.set(1, "One")
+#   MyAwesomeCache.get(1) # => "One"
+#   MyAwesomeCache.delete(1)
+#   MyAwesomeCache.get(1) # => 10
 class Cachetastic::Caches::Base
 
+  # Used to store a list of all the caches registered with the system.
+  # In order for a cache to be registered it must extend Cachetastic::Caches::Base.
   class RegisteredCaches
     include Singleton
     
+    # list of all caches registered with the system.
     attr_reader :list
     
     def initialize
@@ -16,22 +44,23 @@ class Cachetastic::Caches::Base
   # using class << self means we don't have to prefix each method with 'self.'
   class << self
     
+    # Returns a list of all registered caches in the system.
     def all_registered_caches
       RegisteredCaches.instance.list
     end
     
-    def inherited(child)
-      # puts "child: #{child.inspect}"
-      all_registered_caches << child.to_s
-      # puts "all_registered_caches: #{all_registered_caches.inspect}"
-    end
-    
+    # Returns an object from the cache for a given key.
+    # If the object comes back as nil and a block is given
+    # that block will be run and the results of the block
+    # will be run. This can be used to JIT caches, just make
+    # sure in the block to call the set method because the
+    # results of the block are not automatically cached.
     def get(key)
       res = nil
       do_with_logging(:get, key) do
         res = store.get(key.to_s)
         if res.nil?
-          res = yield if block_given?
+          res = yield key if block_given?
         else
           res = unmarshall(res)
         end
@@ -40,18 +69,16 @@ class Cachetastic::Caches::Base
       res
     end
     
+    # Set a particular object info the cache for the given key.
+    # An optional third parameter sets the expiry time for the object in the cache.
+    # The default for this expiry is set as either 0, meaning it never expires, or
+    # if there's a default_expiry time set in the config file, that file will be
+    # used.
+    # If there is an expiry_swing set in the config file it will be +/- to the
+    # expiry time. See also: calculate_expiry_time
     def set(key, value, expiry = (store.all_options["default_expiry"] || 0))
       do_with_logging(:set, key) do
-        exp_swing = store.all_options["expiry_swing"]
-        if exp_swing
-          swing = rand(exp_swing.to_i)
-          case rand(2)
-          when 0
-            expiry = (expiry.to_i + swing)
-          when 1
-            expiry = (expiry.to_i - swing)
-          end
-        end
+        expiry = calculate_expiry_time(expiry)
         store.set(key.to_s, marshall(value), expiry.to_i)
         logger.info('', '', :expiry, cache_name, key, expiry.to_i)
         value
@@ -60,38 +87,74 @@ class Cachetastic::Caches::Base
     
     alias_method :put, :set
     
+    # Deletes an object from the cache. The optional delay parameter
+    # sets an offset, in seconds, for when the object should get deleted.
+    # The default of 0 means the object gets deleted right away.
     def delete(key, delay = 0)
       do_with_logging(:delete, key) do
         store.delete(key.to_s, delay)
       end
     end
     
+    # Expires all objects for this cache.
     def expire_all
       store.expire_all
       logger.info('', '', :expired, cache_name)
     end
     
+    # Raises a MethodNotImplemented exception. This method should be overridden
+    # in the child class to enable a populating the cache with all things that
+    # should be in there. 
     def populate_all
       raise MethodNotImplemented.new("populate_all")
     end
     
+    # A convenience method that returns statistics for the underlying Cachetastic::Stores::Base for the cache.
     def stats
       store.stats
     end
     
+    # Returns a 'methodize' version of the cache's class name. This gets used in logging,
+    # namespacing, and as the key in the Cachetastic::Connection class.
+    #   MyAwesomeCache.cache # => "my_awesome_cache"
+    #   Cachetastic::Caches::Base # => "cachetastic_caches_base"
     def cache_name
       self.name.methodize
     end
-
+    
+    # Returns the underlying Cachetastic::Stores::Base for this cache.
     def store
       cache_conn_instance.get(cache_name)
     end
     
+    # Returns the Cachetastic::Logger for the underlying Cachetastic::Stores::Base.
     def logger
       store.logger
     end
     
     private
+    # If the expiry time is set to 60 minutes and the expiry_swing time is set to
+    # 15 minutes, this method will return a number between 45 minutes and 75 minutes.
+    def calculate_expiry_time(expiry) # :doc:
+      exp_swing = store.all_options["expiry_swing"]
+      if exp_swing
+        swing = rand(exp_swing.to_i)
+        case rand(2)
+        when 0
+          expiry = (expiry.to_i + swing)
+        when 1
+          expiry = (expiry.to_i - swing)
+        end
+      end
+      expiry
+    end
+    
+    def inherited(child)
+      # puts "child: #{child.inspect}"
+      all_registered_caches << child.to_s
+      # puts "all_registered_caches: #{all_registered_caches.inspect}"
+    end
+    
     def marshall(value)
       return case store.all_options["marshall_method"]
       when "yaml"

data/lib/caches/cachetastic_caches_page_cache.rb

@@ -1,2 +1,6 @@
+# Used by the Mongrel Page Cache Handler gem for page caching.
+# Future functionality may be added to this class to allow for
+# things such as deleting a certain page/set of pages based on
+# regex, etc...
 class Cachetastic::Caches::PageCache < Cachetastic::Caches::Base
 end

data/lib/caches/cachetastic_caches_rails_session_cache.rb

@@ -1,2 +1,3 @@
+# Used for storing Rails sessions.
 class Cachetastic::Caches::RailsSessionCache < Cachetastic::Caches::Base
 end

data/lib/cachetastic.rb

@@ -7,18 +7,20 @@ require 'yaml'
 require 'zlib'
 require 'pp'
 
-module Cachetastic
-  module Caches
-    module ActiveRecord
+module Cachetastic #:nodoc:#
+  module Caches #:nodoc:#
+    module ActiveRecord #:nodoc:#
     end
   end
-  module Stores
+  module Stores #:nodoc:#
   end
-  module Helpers
-    module ActiveRecord
+  module Helpers #:nodoc:#
+    module ActiveRecord #:nodoc:#
     end
   end
 end
+module ActiveRecord #:nodoc:#
+end
 
 require 'cachetastic_connection'
 require 'cachetastic_logger'
@@ -26,8 +28,10 @@ require 'caches/cachetastic_caches_base'
 require 'caches/cachetastic_caches_page_cache'
 require 'caches/cachetastic_caches_rails_session_cache'
 require 'stores/cachetastic_stores_base'
+require 'stores/cachetastic_stores_store_object'
 require 'stores/cachetastic_stores_memcache'
 require 'stores/cachetastic_stores_local_memory'
+require 'stores/cachetastic_stores_file'
 require 'helpers/cachetastic_helpers_active_record'
 require 'rails_extensions/cachetastic_active_record_base'
 require 'rails_extensions/cgi_session_cachetastic_store'

data/lib/cachetastic_connection.rb

@@ -8,8 +8,8 @@ class Cachetastic::Connection
     self.connections = {}
   end
   
-  # Takes the name of the cache and returns back the store object associated with the cache.
-  # If the store object doesn't exist of the the store is no longer valid a new one is
+  # Takes the name of the cache, that's been methodized, and returns back the store object associated with the cache.
+  # If the store object doesn't exist or if the store is no longer valid (store.valid?) a new one is
   # created and returned.
   def get(name)
     name = name.to_sym

data/lib/helpers/cachetastic_helpers_active_record.rb

@@ -1,7 +1,12 @@
 module Cachetastic
   module Helpers
+    # These helpers get added to ActiveRecord at both class and instance levels.
     module ActiveRecord
       
+      # Returns the Cachetastic::Caches::Base object associated with the ActiveRecord model.
+      # If a cache hasn't been defined the one will be created on the fly.
+      # The cache for the ActiveRecord model is expected to be defined as:
+      # Cachetastic::Caches::ActiveRecord::MODEL_NAME_HERE
       def cache_class
         n = self.class.name
         n = self.name if n == "Class"
@@ -17,7 +22,12 @@ module Cachetastic
         c_name.constantize
       end
       
-      def cache(key, expiry = 0)
+      # How much did I want to call this method cache?? It originally was that, but
+      # in Rails 2.0 they decided to use that name, so I had to rename this method.
+      # This method will attempt to get an object from the cache for a given key.
+      # If the object is nil and a block is given the block will be run, and the results
+      # of the block will be automatically cached.
+      def cacher(key, expiry = 0)
         cache_class.get(key) do
           if block_given?
             res = yield
@@ -26,6 +36,7 @@ module Cachetastic
         end
       end
       
+      # Expires all the objects associated with this ActiveRecord model's cache.
       def expire_all
         cache_class.expire_all
       end

data/lib/rails_extensions/cachetastic_active_record_base.rb

@@ -5,6 +5,10 @@ class ActiveRecord::Base
   class << self
     include Cachetastic::Helpers::ActiveRecord # include helpers at class level
     
+    # Returns an object from the cache for a given key.
+    # If the object returned is nil and the self_populate parameter is true
+    # then the key will be used to try and find the object in the database,
+    # set the object into the cache, and then return the object.
     def get_from_cache(key, self_populate = false)
       res = cache_class.get(key)
       if res.nil? && self_populate
@@ -16,20 +20,26 @@ class ActiveRecord::Base
       res
     end
     
+    # Deletes an object from the cache for a given key.
     def delete_from_cache(key)
       cache_class.delete(key)
     end
     
+    # Sets an object into the cache for a given key.
     def set_into_cache(key, value, expiry = 0)
       cache_class.set(key, value, expiry)
     end
     
   end
   
+  # Unless the object is a new ActiveRecord object this method will store
+  # the object in the cache using the object's ID as the key.
   def cache_self
     cache_class.set(self.id, self) unless self.new_record?
   end
   
+  # Unless the object is a new ActiveRecord object this method will delete
+  # the object in the cache using the object's ID as the key.
   def uncache_self
     cache_class.delete(self.id) unless self.new_record?
   end

data/lib/rails_extensions/cgi_session_cachetastic_store.rb

@@ -1,15 +1,20 @@
 require 'cgi'
 require 'cgi/session'
- 
-class CGI #:nodoc:all
-  class Session
+
+class CGI #:nodoc:#
+  class Session #:nodoc:#
+    # Allows Rails to use Cachetastic for it's session store.
+    # The setting below needs to happen AFTER the gem has been required, obviously!
+    # In Rails 1.2.6 this is AFTER the initializer block.
+    #   ActionController::Base.session_store = :cachetastic_store
     class CachetasticStore
- 
+
+
       def check_id(id) #:nodoc:#
         /[^0-9a-zA-Z]+/ =~ id.to_s ? false : true
       end
       
-      def initialize(session, options = {})
+      def initialize(session, options = {}) #:nodoc:#
         id = session.session_id
         unless check_id(id)
           raise ArgumentError, "session_id '%s' is invalid" % id
@@ -23,29 +28,29 @@ class CGI #:nodoc:all
       # Restore session state from the session's memcache entry.
       #
       # Returns the session state as a hash.
-      def restore
+      def restore #:nodoc:#
         @session_data = Cachetastic::Caches::RailsSessionCache.get(@session_key) do
           {}
         end
       end
 
       # Save session state to the session's memcache entry.
-      def update
+      def update #:nodoc:#
         Cachetastic::Caches::RailsSessionCache.set(@session_key, @session_data)
       end
     
       # Update and close the session's memcache entry.
-      def close
+      def close #:nodoc:#
         update
       end
 
       # Delete the session's memcache entry.
-      def delete
+      def delete #:nodoc:#
         Cachetastic::Caches::RailsSessionCache.delete(@session_key)
         @session_data = {}
       end
       
-      def data
+      def data #:nodoc:#
         @session_data
       end
 

data/lib/stores/cachetastic_stores_base.rb

@@ -1,3 +1,17 @@
+# This class is the interface used to develop stores for caches.
+# Stores are where the data is actually held. These could be local memory,
+# memcached, a database, the file system, etc...
+# If you implement this API, then you should be able to plug in different
+# stores for your caches without having to change any of your code.
+# 
+# === Methods that need to be implemented:
+# * setup - used to setup the implementation of the store.
+# * set(key, object, expiry) - sets an object into the store using the given key and the expiry time.
+# * get(key) - returns an object from the store for a given key.
+# * delete(key, delay) - deletes an object from the store for a given key. If the store supports it, a delay can be used.
+# * expire_all - expires all objects in the store for a given cache.
+# * stats - returns statistics for the store.
+# * valid? - used to test whether or not the store is still valid. If this returns false a new instance of the store is created by Cachetastic::Connection
 class Cachetastic::Stores::Base
   
   attr_reader :all_options
@@ -16,32 +30,29 @@ class Cachetastic::Stores::Base
       self.logger.debug(self.name, :options, self.all_options.inspect)
     end
   end
-  
-  def valid?
-    false
-  end
 
-  [:setup, :set, :get, :delete, :expire_all, :stats].each do |meth|
+  [:setup, :set, :get, :delete, :expire_all, :stats, "valid?"].each do |meth|
     define_method(meth) do |*args|
       raise MethodNotImplemented.new(meth)
     end
   end
   
+  # Returns true/or falsed based on whether or not the debug setting is set to true in the
+  # configuration file. If the config setting is set, then false is returned.
   def debug?
     ivar_cache(:debug) do
       (self.all_options["debug"] == true || false)
     end
   end
   
-  def configure
-    @all_options = Cachetastic::Stores::Base.get_options(self.name)
-    @store_options = (self.all_options["store_options"] || {})
-    @servers = self.all_options["servers"]
-    @logging = (self.all_options["logging"] || {})
-    @logger = Cachetastic::Logger.new(self.logging, self.name)
-  end
-  
   class << self
+    # Merges options for the store in the configuration file with the cachetastic_default_options 
+    # found in the configuration file, and returns the results.
+    # Options need to be specified in the configuration file as the methodized name of the store with
+    # _options attached at the end.
+    # Examples:
+    #   Cachetastic::Caches::PageCache # => cachetastic_caches_page_cache_options
+    #   MyAwesomeCache # => my_awesome_cache_options
     def get_options(name)
       options = app_config.cachetastic_default_options
       options.merge!(app_config.send(name.methodize + "_options") || {})
@@ -50,4 +61,13 @@ class Cachetastic::Stores::Base
     end
   end
   
+  private
+  def configure
+    @all_options = Cachetastic::Stores::Base.get_options(self.name)
+    @store_options = (self.all_options["store_options"] || {})
+    @servers = self.all_options["servers"]
+    @logging = (self.all_options["logging"] || {})
+    @logger = Cachetastic::Logger.new(self.logging, self.name)
+  end
+  
 end