Merge with docrails

2 files changed, 29 insertions, 23 deletions

diff --git a/actionpack/lib/action_controller/caching/fragments.rb b/actionpack/lib/action_controller/caching/fragments.rb
index c41b1a12cf..95cba0e411 100644
--- a/actionpack/lib/action_controller/caching/fragments.rb
+++ b/actionpack/lib/action_controller/caching/fragments.rb
@@ -83,15 +83,23 @@ module ActionController #:nodoc:
         end
       end
 
-      # Name can take one of three forms:
-      # * String: This would normally take the form of a path like "pages/45/notes"
-      # * Hash: Is treated as an implicit call to url_for, like { :controller => "pages", :action => "notes", :id => 45 }
-      # * Regexp: Will destroy all the matched fragments, example:
-      #     %r{pages/\d*/notes}
-      #   Ensure you do not specify start and finish in the regex (^$) because
-      #   the actual filename matched looks like ./cache/filename/path.cache
-      #   Regexp expiration is only supported on caches that can iterate over
-      #   all keys (unlike memcached).
+      # Removes fragments from the cache.
+      #
+      # +key+ can take one of three forms:
+      # * String - This would normally take the form of a path, like
+      #   <tt>"pages/45/notes"</tt>.
+      # * Hash - Treated as an implicit call to +url_for+, like
+      #   <tt>{:controller => "pages", :action => "notes", :id => 45}</tt>
+      # * Regexp - Will remove any fragment that matches, so
+      #   <tt>%r{pages/\d*/notes}</tt> might remove all notes. Make sure you
+      #   don't use anchors in the regex (<tt>^</tt> or <tt>$</tt>) because
+      #   the actual filename matched looks like
+      #   <tt>./cache/filename/path.cache</tt>. Note: Regexp expiration is
+      #   only supported on caches that can iterate over all keys (unlike
+      #   memcached).
+      #
+      # +options+ is passed through to the cache store's <tt>delete</tt>
+      # method (or <tt>delete_matched</tt>, for Regexp keys.)
       def expire_fragment(key, options = nil)
         return unless cache_configured?
 
diff --git a/actionpack/lib/action_controller/caching/pages.rb b/actionpack/lib/action_controller/caching/pages.rb
index a70ed72f03..22e4fbec43 100644
--- a/actionpack/lib/action_controller/caching/pages.rb
+++ b/actionpack/lib/action_controller/caching/pages.rb
@@ -33,28 +33,26 @@ module ActionController #:nodoc:
     #
     # Additionally, you can expire caches using Sweepers that act on changes in the model to determine when a cache is supposed to be
     # expired.
-    #
-    # == Setting the cache directory
-    #
-    # 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.
-    #
-    # == Setting the cache extension
-    #
-    # 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.
     module Pages
       def self.included(base) #:nodoc:
         base.extend(ClassMethods)
         base.class_eval do
           @@page_cache_directory = defined?(Rails.public_path) ? Rails.public_path : ""
+          ##
+          # :singleton-method:
+          # 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.
           cattr_accessor :page_cache_directory
 
           @@page_cache_extension = '.html'
+          ##
+          # :singleton-method:
+          # 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.
           cattr_accessor :page_cache_extension
         end
       end