Merge branch 'master' of git://github.com/lifo/docrails

4 files changed, 46 insertions, 44 deletions

diff --git a/activesupport/lib/active_support/benchmarkable.rb b/activesupport/lib/active_support/benchmarkable.rb
index e303eaa5ce..cc94041a1d 100644
--- a/activesupport/lib/active_support/benchmarkable.rb
+++ b/activesupport/lib/active_support/benchmarkable.rb
@@ -3,28 +3,28 @@ require 'active_support/core_ext/hash/keys'
 
 module ActiveSupport
   module Benchmarkable
-    # Allows you to measure the execution time of a block
-    # in a template and records the result to the log. Wrap this block around
-    # expensive operations or possible bottlenecks to get a time reading
-    # for the operation. For example, let's say you thought your file
-    # processing method was taking too long; you could wrap it in a benchmark block.
+    # Allows you to measure the execution time of a block in a template and records the result to
+    # the log. Wrap this block around expensive operations or possible bottlenecks to get a time
+    # reading for the operation. For example, let's say you thought your file processing method
+    # was taking too long; you could wrap it in a benchmark block.
     #
     #  <% benchmark "Process data files" do %>
     #    <%= expensive_files_operation %>
     #  <% end %>
     #
-    # That would add something like "Process data files (345.2ms)" to the log,
-    # which you can then use to compare timings when optimizing your code.
+    # That would add something like "Process data files (345.2ms)" to the log, which you can then
+    # use to compare timings when optimizing your code.
     #
-    # You may give an optional logger level as the :level option.
-    # (:debug, :info, :warn, :error); the default value is :info.
+    # You may give an optional logger level (:debug, :info, :warn, :error) as the :level option.
+    # The default logger level value is :info.
     #
     #  <% benchmark "Low-level files", :level => :debug do %>
     #    <%= lowlevel_files_operation %>
     #  <% end %>
     #
-    # Finally, you can pass true as the third argument to silence all log activity
-    # inside the block. This is great for boiling down a noisy block to just a single statement:
+    # Finally, you can pass true as the third argument to silence all log activity (other than the
+    # timing information) from inside the block. This is great for boiling down a noisy block to 
+    # just a single statement that produces one log line:
     #
     #  <% benchmark "Process data files", :level => :info, :silence => true do %>
     #    <%= expensive_and_chatty_files_operation %>
diff --git a/activesupport/lib/active_support/cache.rb b/activesupport/lib/active_support/cache.rb
index 10c457bb1d..85692428e3 100644
--- a/activesupport/lib/active_support/cache.rb
+++ b/activesupport/lib/active_support/cache.rb
@@ -116,31 +116,32 @@ module ActiveSupport
     #   cache.read("city")   # => "Duckburgh"
     #
     # Keys are always translated into Strings and are case sensitive. When an
-    # object is specified as a key, its +cache_key+ method will be called if it
-    # is defined. Otherwise, the +to_param+ method will be called. Hashes and
-    # Arrays can be used as keys. The elements will be delimited by slashes
-    # and Hashes elements will be sorted by key so they are consistent.
+    # object is specified as a key and has a +cache_key+ method defined, this
+    # method will be called to define the key.  Otherwise, the +to_param+
+    # method will be called. Hashes and Arrays can also be used as keys. The
+    # elements will be delimited by slashes, and the elements within a Hash
+    # will be sorted by key so they are consistent.
     #
     #   cache.read("city") == cache.read(:city)   # => true
     #
     # Nil values can be cached.
     #
-    # If your cache is on a shared infrastructure, you can define a namespace for
-    # your cache entries. If a namespace is defined, it will be prefixed on to every
-    # key. The namespace can be either a static value or a Proc. If it is a Proc, it
-    # will be invoked when each key is evaluated so that you can use application logic
-    # to invalidate keys.
+    # If your cache is on a shared infrastructure, you can define a namespace
+    # for your cache entries. If a namespace is defined, it will be prefixed on
+    # to every key. The namespace can be either a static value or a Proc. If it
+    # is a Proc, it will be invoked when each key is evaluated so that you can
+    # use application logic to invalidate keys.
     #
     #   cache.namespace = lambda { @last_mod_time }  # Set the namespace to a variable
     #   @last_mod_time = Time.now  # Invalidate the entire cache by changing namespace
     #
     #
-    # Caches can also store values in a compressed format to save space and reduce
-    # time spent sending data. Since there is some overhead, values must be large
-    # enough to warrant compression. To turn on compression either pass
-    # <tt>:compress => true</tt> in the initializer or to +fetch+ or +write+.
-    # To specify the threshold at which to compress values, set
-    # <tt>:compress_threshold</tt>. The default threshold is 32K.
+    # Caches can also store values in a compressed format to save space and
+    # reduce time spent sending data. Since there is overhead, values must be
+    # large enough to warrant compression. To turn on compression either pass
+    # <tt>:compress => true</tt> in the initializer or as an option to +fetch+
+    # or +write+. To specify the threshold at which to compress values, set the
+    # <tt>:compress_threshold</tt> option. The default threshold is 32K.
     class Store
 
       cattr_accessor :logger, :instance_writer => true
@@ -180,11 +181,11 @@ module ActiveSupport
       # Fetches data from the cache, using the given key. If there is data in
       # the cache with the given key, then that data is returned.
       #
-      # If there is no such data in the cache (a cache miss occurred),
-      # then nil will be returned. However, if a block has been passed, then
-      # that block will be run in the event of a cache miss. The return value
-      # of the block will be written to the cache under the given cache key,
-      # and that return value will be returned.
+      # If there is no such data in the cache (a cache miss), then nil will be
+      # returned. However, if a block has been passed, that block will be run
+      # in the event of a cache miss. The return value of the block will be
+      # written to the cache under the given cache key, and that return value
+      # will be returned.
       #
       #   cache.write("today", "Monday")
       #   cache.fetch("today")  # => "Monday"
@@ -205,10 +206,11 @@ module ActiveSupport
       # in a compressed format.
       #
       #
-      # Setting <tt>:expires_in</tt> will set an expiration time on the cache. All caches
-      # support auto expiring content after a specified number of seconds. This value can
-      # be specified as an option to the construction in which call all entries will be
-      # affected. Or it can be supplied to the +fetch+ or +write+ method for just one entry.
+      # Setting <tt>:expires_in</tt> will set an expiration time on the cache.
+      # All caches support auto-expiring content after a specified number of
+      # seconds. This value can be specified as an option to the constructor
+      # (in which case all entries will be affected), or it can be supplied to
+      # the +fetch+ or +write+ method to effect just one entry.
       #
       #   cache = ActiveSupport::Cache::MemoryStore.new(:expires_in => 5.minutes)
       #   cache.write(key, value, :expires_in => 1.minute)  # Set a lower value for one entry
diff --git a/activesupport/lib/active_support/core_ext/string/output_safety.rb b/activesupport/lib/active_support/core_ext/string/output_safety.rb
index 172b7258ef..3bf4edbdef 100644
--- a/activesupport/lib/active_support/core_ext/string/output_safety.rb
+++ b/activesupport/lib/active_support/core_ext/string/output_safety.rb
@@ -137,14 +137,14 @@ module ActiveSupport #:nodoc:
 
     UNSAFE_STRING_METHODS.each do |unsafe_method|
       class_eval <<-EOT, __FILE__, __LINE__
-        def #{unsafe_method}(*args, &block)
-          to_str.#{unsafe_method}(*args, &block)
-        end
-
-        def #{unsafe_method}!(*args)
-          @dirty = true
-          super
-        end
+        def #{unsafe_method}(*args, &block)       # def gsub(*args, &block)
+          to_str.#{unsafe_method}(*args, &block)  #   to_str.gsub(*args, &block)
+        end                                       # end
+
+        def #{unsafe_method}!(*args)              # def gsub!(*args)
+          @dirty = true                           #   @dirty = true
+          super                                   #   super
+        end                                       # end
       EOT
     end
 
diff --git a/activesupport/lib/active_support/testing/assertions.rb b/activesupport/lib/active_support/testing/assertions.rb
index 05da50e150..3864b1f5a6 100644
--- a/activesupport/lib/active_support/testing/assertions.rb
+++ b/activesupport/lib/active_support/testing/assertions.rb
@@ -68,7 +68,7 @@ module ActiveSupport
       #
       # A error message can be specified.
       #
-      #   assert_no_difference 'Article.count', "An Article should not be destroyed" do
+      #   assert_no_difference 'Article.count', "An Article should not be created" do
       #     post :create, :article => invalid_attributes
       #   end
       def assert_no_difference(expression, message = nil, &block)