Cache documentation cleanup

padrino-cache/lib/padrino-cache.rb

@@ -6,7 +6,7 @@
 module Padrino
   class << self
     ##
-    # Returns the caching engine
+    # Returns the caching engine.
     #
     # @example
     #   # with: Padrino.cache = Padrino::Cache::Store::File.new(/my/cache/path)
@@ -15,13 +15,12 @@ class << self
     #   Padrino.cache.delete('val')
     #   Padrino.cache.flush
     #
-    # @api public
     def cache
       @_cache
     end
 
     ##
-    # Set the caching engine
+    # Set the caching engine.
     #
     # @param value
     #   Instance of Padrino::Cache::Store
@@ -41,11 +40,10 @@ def cache
     #   Padrino.cache.delete('val')
     #   Padrino.cache.flush
     #
-    # @api public
     def cache=(value)
       @_cache= value
     end
-  end # self
+  end
 
   ##
   # This component enables caching of an application's response contents on
@@ -71,7 +69,7 @@ class << self
       #
       #   set :cache, Padrino::Cache::Store::File.new(File.join(app.root, 'tmp', 'cache'))
       #
-      # However, you can also change the file store easiily in your app.rb:
+      # However, you can also change the file store easily in your app.rb:
       #
       #   set :cache, Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
       #   set :cache, Padrino::Cache::Store::Memcache.new(::Dalli::Client.new('127.0.0.1:11211', :exception_retry_limit => 1))
@@ -87,7 +85,6 @@ class << self
       #   MyApp.cache.delete('val')
       #   MyApp.cache.flush
       #
-      # @api public
       def registered(app)
         app.helpers Padrino::Cache::Helpers::CacheStore
         app.helpers Padrino::Cache::Helpers::Fragment
@@ -97,12 +94,11 @@ def registered(app)
       end
       alias :included :registered
 
-      # @private
-      def padrino_route_added(route, verb, path, args, options, block) # @private
+      def padrino_route_added(route, verb, path, args, options, block)
         Padrino::Cache::Helpers::Page.padrino_route_added(route, verb, path, args, options, block)
       end
     end
 
     Padrino.cache = Store::Memory.new(50)
-  end # Cache
-end # Padrino
+  end
+end

padrino-cache/lib/padrino-cache/helpers/cache_store.rb

@@ -1,17 +1,15 @@
 module Padrino
   module Cache
     module Helpers
-      module CacheStore # @private
-
-        # @api private
+      module CacheStore
         def expire(*key)
           if key.size == 1 and (key.first.is_a?(String) or key.first.is_a?(Symbol))
             settings.cache.delete(key.first)
           else
             settings.cache.delete(self.class.url(*key))
           end
         end
-      end # CacheStore
-    end # Helpers
-  end # Cache
-end # Padrino
+      end
+    end
+  end
+end

padrino-cache/lib/padrino-cache/helpers/fragment.rb

@@ -8,10 +8,10 @@ module Helpers
       #
       # Possible uses for fragment caching might include:
       #
-      # * a 'feed' of some items on a page
-      # * output fetched (by proxy) from an API on a third-party site
-      # * parts of your page which are largely static/do not need re-rendering every request
-      # * any output which is expensive to render
+      # - a 'feed' of some items on a page
+      # - output fetched (by proxy) from an API on a third-party site
+      # - parts of your page which are largely static/do not need re-rendering every request
+      # - any output which is expensive to render
       #
       module Fragment
         include Padrino::Helpers::OutputHelpers
@@ -41,13 +41,12 @@ module Fragment
         #           render 'partials/feedcontent'
         #         end
         #
-        #         # Below outputs @feed somewhere in its markup
+        #         # Below outputs @feed somewhere in its markup.
         #         render 'feeds/show'
         #       end
         #     end
         #   end
         #
-        # @api public
         def cache(key, opts = nil, &block)
           if settings.caching?
             began_at = Time.now
@@ -62,10 +61,10 @@ def cache(key, opts = nil, &block)
             end
           else
             value = capture_html(&block)
-            concat_content(value)   
+            concat_content(value)
           end
         end
-      end # Fragment
-    end # Helpers
-  end # Cache
-end # Padrino
+      end
+    end
+  end
+end

padrino-cache/lib/padrino-cache/helpers/page.rb

@@ -7,11 +7,11 @@ module Helpers
       ##
       # Page caching is easy to integrate into your application. To turn it on, simply provide the
       # <tt>:cache => true</tt> option on either a controller or one of its routes.
-      # By default, cached content is persisted with a "file store"--that is, in a
+      # By default, cached content is persisted with a "file store" --that is, in a
       # subdirectory of your application root.
       #
       # @example
-      #   # Setting content expiry time
+      #   # Setting content expiry time.
       #   class CachedApp < Padrino::Application
       #     enable :caching          # turns on caching mechanism
       #
@@ -20,7 +20,7 @@ module Helpers
       #
       #       get '/entries' do
       #         # expires_in 15 => can also be defined inside a single route
-      #         'just broke up eating twinkies lol'
+      #         'Just broke up eating twinkies, lol'
       #       end
       #
       #       get '/post/:id' do
@@ -55,11 +55,10 @@ module Page
         #
         #     get '/entries' do
         #       # expires_in 15 => can also be defined inside a single route
-        #       'just broke up eating twinkies lol'
+        #       'Just broke up eating twinkies, lol'
         #     end
         #   end
         #
-        # @api public
         def expires_in(time)
           @route.cache_expires_in = time if @route
           @_last_expires_in       = time
@@ -85,18 +84,16 @@ def expires_in(time)
         # @example
         #     get '/foo', :cache => true do
         #       cache_key { param[:id] }
-        #       "my id is #{param[:id}"
+        #       "My id is #{param[:id}"
         #     end
         #   end
         #
-        # @api public
         def cache_key(name = nil, &block)
           raise "Can not provide both cache_key and a block" if name && block
           @route.cache_key = block_given? ? block : name
         end
 
-        # @private
-        def self.padrino_route_added(route, verb, path, args, options, block) # @private
+        def self.padrino_route_added(route, verb, path, args, options, block)
           if route.cache and %w(GET HEAD).include?(verb)
             route.before_filters do
               if settings.caching?
@@ -106,7 +103,6 @@ def self.padrino_route_added(route, verb, path, args, options, block) # @private
                 logger.debug "GET Cache", began_at, @route.cache_key || env['PATH_INFO'] if defined?(logger) && value
 
                 if value
-                  # content_type(value[:content_type]) if value[:content_type]
                   halt 200, value
                 end
               end
@@ -132,13 +128,12 @@ def self.padrino_route_added(route, verb, path, args, options, block) # @private
 
         private
         ##
-        # Resolve the cache_key when it's a block in the correct context
-        #@api private
+        # Resolve the cache_key when it's a block in the correct context.
+        #
         def resolve_cache_key
           @route.cache_key.is_a?(Proc) ? instance_eval(&@route.cache_key) : @route.cache_key
         end
-
-      end # Page
-    end # Helpers
-  end # Cache
-end # Padrino
+      end
+    end
+  end
+end

padrino-cache/lib/padrino-cache/parser.rb

@@ -1,6 +1,5 @@
 module Padrino
   module Cache
-
     ##
     # Defines a padrino parser for our cache store.
     #
@@ -21,7 +20,7 @@ def self.encode(code)
 
       ##
       # With Parser::Marshal we will store
-      # text and object in a marshalled format.
+      # text and object in a marshaled format.
       #
       module Marshal
         def self.decode(code)
@@ -32,6 +31,6 @@ def self.encode(code)
           ::Marshal.dump(code)
         end
       end
-    end # Parser
-  end # Cache
-end # Padrino
+    end
+  end
+end

padrino-cache/lib/padrino-cache/store.rb

@@ -13,6 +13,6 @@ module Store
       autoload :Memory,   'padrino-cache/store/memory'
       autoload :Redis,    'padrino-cache/store/redis'
       autoload :Mongo,    'padrino-cache/store/mongo'
-    end # Store
-  end # Cache
-end # Padrino
+    end
+  end
+end

padrino-cache/lib/padrino-cache/store/base.rb

@@ -5,9 +5,8 @@ module Store
       # Abstract Cache Store
       #
       class Base
-
         ##
-        # Get the cache parser strategy
+        # Get the cache parser strategy.
         #
         # By default is plain, otherwise you can set **Marshal** or write your own.
         #
@@ -16,15 +15,16 @@ def parser
         end
 
         ##
-        # Set the caching parser strategy
+        # Set the caching parser strategy.
         #
         # @param value
-        #   Module of Padrino::Cache::Parser or any that respond to encode/decode
+        #   Module of Padrino::Cache::Parser or any that respond to encode/decode.
         #
         # @example
+        #   # shorter version:
         #   Padrino.cache.parser = :plain
         #   Padrino.cache.parser = :marshal
-        #   # shortcuts for:
+        #   # longer version:
         #   Padrino.cache.parser = Padrino::Cache::Parser::Plain
         #   Padrino.cache.parser = Padrino::Cache::Parser::Marshal
         #
@@ -34,7 +34,7 @@ def parser
         #   require 'oj'
         #   module FastJSONParser
         #     def self.encode(value)
-        #       OJ.dump(value)
+        #       Oj.dump(value)
         #     end
         #
         #     def self.decode(value)
@@ -51,14 +51,12 @@ def parser=(mod)
           @_parser=mod
         end
 
-        # @private
         def initialize(options={})
           @never = -1
           self.parser = options[:parser] || :plain
         end
 
         private
-
         def get_expiry( opts )
           if opts && opts[:expires_in] && opts[:expires_in] != -1
             expires_in = opts[:expires_in].to_i
@@ -72,8 +70,7 @@ def get_expiry( opts )
         def now_before?( expiry )
           expiry.to_i == @never || expiry.to_i > Time.now.to_i
         end
-      end # Base
-    end # Store
-  end # Cache
-end # Padrino
-
+      end
+    end
+  end
+end