update AC::Caching documentation [ci skip]

1 files changed, 52 insertions, 39 deletions

diff --git a/actionpack/lib/action_controller/caching/pages.rb b/actionpack/lib/action_controller/caching/pages.rb
index 73b8cd383c..3cf8d965ff 100644
--- a/actionpack/lib/action_controller/caching/pages.rb
+++ b/actionpack/lib/action_controller/caching/pages.rb
@@ -1,60 +1,72 @@
 require 'fileutils'
 require 'active_support/core_ext/class/attribute_accessors'
 
-module ActionController #:nodoc:
+module ActionController
   module Caching
-    # Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server
-    # can serve without going through Action Pack. This is the fastest way to cache your content as opposed to going dynamically
-    # through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages
-    # where all visitors are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are
-    # a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less
-    # likely candidates.
+    # Page caching is an approach to caching where the entire action output of is
+    # stored as a HTML file that the web server can serve without going through
+    # Action Pack. This is the fastest way to cache your content as opposed to going
+    # dynamically through the process of generating the content. Unfortunately, this
+    # incredible speed-up is only available to stateless pages where all visitors are
+    # treated the same. Content management systems -- including weblogs and wikis --
+    # have many pages that are a great fit for this approach, but account-based systems
+    # where people log in and manipulate their own data are often less likely candidates.
     #
-    # Specifying which actions to cache is done through the <tt>caches_page</tt> class method:
+    # Specifying which actions to cache is done through the +caches_page+ class method:
     #
     #   class WeblogController < ActionController::Base
     #     caches_page :show, :new
     #   end
     #
-    # This will generate cache files such as <tt>weblog/show/5.html</tt> and <tt>weblog/new.html</tt>, which match the URLs used
-    # that would normally trigger dynamic page generation. Page caching works by configuring a web server to first check for the
-    # existence of files on disk, and to serve them directly when found, without passing the request through to Action Pack.
-    # This is much faster than handling the full dynamic request in the usual way.
+    # This will generate cache files such as <tt>weblog/show/5.html</tt> and
+    # <tt>weblog/new.html</tt>, which match the URLs used that would normally trigger
+    # dynamic page generation. Page caching works by configuring a web server to first
+    # check for the existence of files on disk, and to serve them directly when found,
+    # without passing the request through to Action Pack. This is much faster than
+    # handling the full dynamic request in the usual way.
     #
-    # Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache
-    # is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends:
+    # Expiration of the cache is handled by deleting the cached file, which results
+    # in a lazy regeneration approach where the cache is not restored before another
+    # hit is made against it. The API for doing so mimics the options from +url_for+ and friends:
     #
     #   class WeblogController < ActionController::Base
     #     def update
     #       List.update(params[:list][:id], params[:list])
-    #       expire_page :action => "show", :id => params[:list][:id]
-    #       redirect_to :action => "show", :id => params[:list][:id]
+    #       expire_page action: 'show', id: params[:list][:id]
+    #       redirect_to action: 'show', id: params[:list][:id]
     #     end
     #   end
     #
-    # Additionally, you can expire caches using Sweepers that act on changes in the model to determine when a cache is supposed to be
-    # expired.
+    # Additionally, you can expire caches using Sweepers that act on changes in
+    # the model to determine when a cache is supposed to be expired.
     module Pages
       extend ActiveSupport::Concern
 
       included do
-        # The cache directory should be the document root for the web server and is set using <tt>Base.page_cache_directory = "/document/root"</tt>.
-        # For Rails, this directory has already been set to Rails.public_path (which is usually set to <tt>Rails.root + "/public"</tt>). Changing
-        # this setting can be useful to avoid naming conflicts with files in <tt>public/</tt>, but doing so will likely require configuring your
-        # web server to look in the new location for cached files.
+        # The cache directory should be the document root for the web server and is
+        # set using <tt>Base.page_cache_directory = "/document/root"</tt>. For Rails,
+        # this directory has already been set to Rails.public_path (which is usually
+        # set to <tt>Rails.root + "/public"</tt>). Changing this setting can be useful
+        # to avoid naming conflicts with files in <tt>public/</tt>, but doing so will
+        # likely require configuring your web server to look in the new location for
+        # cached files.
         class_attribute :page_cache_directory
         self.page_cache_directory ||= ''
 
-        # Most Rails requests do not have an extension, such as <tt>/weblog/new</tt>. In these cases, the page caching mechanism will add one in
-        # order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is <tt>.html</tt>.
-        # If you want something else, like <tt>.php</tt> or <tt>.shtml</tt>, just set Base.page_cache_extension. In cases where a request already has an
-        # extension, such as <tt>.xml</tt> or <tt>.rss</tt>, page caching will not add an extension. This allows it to work well with RESTful apps.
+        # Most Rails requests do not have an extension, such as <tt>/weblog/new</tt>.
+        # In these cases, the page caching mechanism will add one in order to make it
+        # easy for the cached files to be picked up properly by the web server. By
+        # default, this cache extension is <tt>.html</tt>. If you want something else,
+        # like <tt>.php</tt> or <tt>.shtml</tt>, just set Base.page_cache_extension.
+        # In cases where a request already has an extension, such as <tt>.xml</tt>
+        # or <tt>.rss</tt>, page caching will not add an extension. This allows it
+        # to work well with RESTful apps.
         class_attribute :page_cache_extension
         self.page_cache_extension ||= '.html'
 
-        # The compression used for gzip. If false (default), the page is not compressed.
-        # If can be a symbol showing the ZLib compression method, for example, :best_compression
-        # or :best_speed or an integer configuring the compression level.
+        # The compression used for gzip. If +false+ (default), the page is not compressed.
+        # If can be a symbol showing the ZLib compression method, for example, <tt>:best_compression</tt>
+        # or <tt>:best_speed</tt> or an integer configuring the compression level.
         class_attribute :page_cache_compression
         self.page_cache_compression ||= false
       end
@@ -62,7 +74,7 @@ module ActionController #:nodoc:
       module ClassMethods
         # Expires the page that was cached with the +path+ as a key.
         #
-        #   expire_page "/lists/show"
+        #   expire_page '/lists/show'
         def expire_page(path)
           return unless perform_caching
           path = page_cache_path(path)
@@ -75,7 +87,7 @@ module ActionController #:nodoc:
 
         # Manually cache the +content+ in the key determined by +path+.
         #
-        #   cache_page "I'm the cached content", "/lists/show"
+        #   cache_page "I'm the cached content", '/lists/show'
         def cache_page(content, path, extension = nil, gzip = Zlib::BEST_COMPRESSION)
           return unless perform_caching
           path = page_cache_path(path, extension)
@@ -90,19 +102,19 @@ module ActionController #:nodoc:
         end
 
         # Caches the +actions+ using the page-caching approach that'll store
-        # the cache in a path within the page_cache_directory that
+        # the cache in a path within the +page_cache_directory+ that
         # matches the triggering url.
         #
-        # You can also pass a :gzip option to override the class configuration one.
+        # You can also pass a <tt>:gzip</tt> option to override the class configuration one.
         #
         #   # cache the index action
         #   caches_page :index
         #
         #   # cache the index action except for JSON requests
-        #   caches_page :index, :if => Proc.new { !request.format.json? }
+        #   caches_page :index, if: Proc.new { !request.format.json? }
         #
         #   # don't gzip images
-        #   caches_page :image, :gzip => false
+        #   caches_page :image, gzip: false
         def caches_page(*actions)
           return unless perform_caching
           options = actions.extract_options!
@@ -144,7 +156,7 @@ module ActionController #:nodoc:
 
       # Expires the page that was cached with the +options+ as a key.
       #
-      #   expire_page :controller => "lists", :action => "show"
+      #   expire_page controller: 'lists', action: 'show'
       def expire_page(options = {})
         return unless self.class.perform_caching
 
@@ -161,10 +173,11 @@ module ActionController #:nodoc:
         end
       end
 
-      # Manually cache the +content+ in the key determined by +options+. If no content is provided, the contents of response.body is used.
-      # If no options are provided, the url of the current request being handled is used.
+      # Manually cache the +content+ in the key determined by +options+. If no content is provided,
+      # the contents of response.body is used. If no options are provided, the url of the current
+      # request being handled is used.
       #
-      #   cache_page "I'm the cached content", :controller => "lists", :action => "show"
+      #   cache_page "I'm the cached content", controller: 'lists', action: 'show'
       def cache_page(content = nil, options = nil, gzip = Zlib::BEST_COMPRESSION)
         return unless self.class.perform_caching && caching_allowed?