activesupport 3.0.0.rc → 3.0.0.rc2

data/CHANGELOG

@@ -1,3 +1,8 @@
+*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
+
+* No material changes (see http://github.com/rails/rails/compare/v3.0.0_RC...v3.0.0_RC2 for gory details)
+
+
 *Rails 3.0.0 [release candidate] (July 26th, 2010)*
 
 * Removed Object#returning, Object#tap should be used instead. [Santiago Pastorino]
@@ -90,7 +95,7 @@
 
 * Rename #metaclass to #singleton_class now that ruby-core has decided [JK]
 
-* New assertions assert_blank and assert_present.  #4299 [Juanjo Bazan] 
+* New assertions assert_blank and assert_present.  #4299 [Juanjo Bazan]
 
 * Use Object#singleton_class instead of #metaclass. Prefer Ruby's choice.  [Jeremy Kemper]
 
@@ -243,10 +248,10 @@ ActiveSupport.escape_html_entities_in_json from true to false to match previousl
 * Fix Ruby's Time marshaling bug in pre-1.9 versions of Ruby: utc instances are now correctly unmarshaled with a utc zone instead of the system local zone [#900 state:resolved] [Luca Guidi, Geoff Buesing]
 
 * Add Array#in_groups which splits or iterates over the array in specified number of groups. #579. [Adrian Mugnolo] Example:
-  
+
   a = (1..10).to_a
-  a.in_groups(3)        #=> [[1, 2, 3, 4], [5, 6, 7, nil], [8, 9, 10, nil]]
-  a.in_groups(3, false) #=> [[1, 2, 3, 4], [5, 6, 7], [8, 9, 10]]
+  a.in_groups(3)        # => [[1, 2, 3, 4], [5, 6, 7, nil], [8, 9, 10, nil]]
+  a.in_groups(3, false) # => [[1, 2, 3, 4], [5, 6, 7], [8, 9, 10]]
 
 * Fix TimeWithZone unmarshaling: coerce unmarshaled Time instances to utc, because Ruby's marshaling of Time instances doesn't respect the zone [Geoff Buesing]
 
@@ -331,7 +336,7 @@ ActiveSupport.escape_html_entities_in_json from true to false to match previousl
 
 * TZInfo: Removing unneeded TimezoneProxy class [Geoff Buesing]
 
-* TZInfo: Removing unneeded TimezoneIndexDefinition, since we're not including Indexes::Timezones [Geoff Buesing] 
+* TZInfo: Removing unneeded TimezoneIndexDefinition, since we're not including Indexes::Timezones [Geoff Buesing]
 
 * Removing unnecessary uses_tzinfo helper from tests, given that TZInfo is now bundled [Geoff Buesing]
 
@@ -339,7 +344,7 @@ ActiveSupport.escape_html_entities_in_json from true to false to match previousl
 
 * TimeWithZone#marshal_load does zone lookup via Time.get_zone, so that tzinfo/Olson identifiers are handled [Geoff Buesing]
 
-* Time.zone= accepts TZInfo::Timezone instances and Olson identifiers; wraps result in TimeZone instance [Geoff Buesing] 
+* Time.zone= accepts TZInfo::Timezone instances and Olson identifiers; wraps result in TimeZone instance [Geoff Buesing]
 
 * TimeWithZone time conversions don't need to be wrapped in TimeOrDateTime, because TZInfo does this internally [Geoff Buesing]
 
@@ -433,7 +438,7 @@ ActiveSupport.escape_html_entities_in_json from true to false to match previousl
 
 * TimeZone#to_s uses UTC rather than GMT; reapplying change that was undone in [8679]. #1689 [Cheah Chu Yeow]
 
-* Time.days_in_month defaults to current year if no year is supplied as argument #10799 [Radar], uses Date.gregorian_leap? to determine leap year, and uses constant lookup to determine days in month [Geoff Buesing]  
+* Time.days_in_month defaults to current year if no year is supplied as argument #10799 [Radar], uses Date.gregorian_leap? to determine leap year, and uses constant lookup to determine days in month [Geoff Buesing]
 
 * Adding Time and DateTime #compare_with_coercion, which layers behavior on #<=> so that any combination of Time, DateTime and ActiveSupport::TimeWithZone instances can be chronologically compared [Geoff Buesing]
 
@@ -510,7 +515,7 @@ ActiveSupport.escape_html_entities_in_json from true to false to match previousl
 
 * Introduce a base class for all test cases used by rails applications. ActiveSupport::TestCase [Michael Koziarski]
 
-  The intention is to use this to reduce the amount of monkeypatching / overriding that 
+  The intention is to use this to reduce the amount of monkeypatching / overriding that
   is done to test/unit's classes.
 
 * Document Enumerable and Hash #to_json.  #9970 [Cheah Chu Yeow]
@@ -679,14 +684,14 @@ ActiveSupport.escape_html_entities_in_json from true to false to match previousl
       <name>David</name>
       <avatar type="file" name="me.jpg" content_type="image/jpg">R0lGODlhkACZAPUAAM5lcfjrtMQCG=\n</avatar>
     </person>
-  
+
   ...becomes:
-  
+
     attributes = { :person => { :name => "David", :avatar => #<StringIO> } }
     attributes[:person][:avatar].content_type      # => "image/jpg"
     attributes[:person][:avatar].original_filename # => "me.jpg"
     attributes[:person][:avatar].read # => binary data of the file
-  
+
   Which is duck-type compatible with the files that you get when doing multipart uploads through HTML.
 
 * Improved multibyte performance by relying less on exception raising #8159 [Blaine]
@@ -889,11 +894,11 @@ public for compatibility.  [Jeremy Kemper]
     class Content < ActiveRecord::Base
       # has a title attribute
     end
- 
+
     class Email < ActiveRecord::Base
       alias_attribute :subject, :title
     end
- 
+
     e = Email.find(1)
     e.title    # => "Superstars"
     e.subject  # => "Superstars"
@@ -942,7 +947,7 @@ public for compatibility.  [Jeremy Kemper]
 * Enhance Symbol#to_proc so it works with list objects, such as multi-dimensional arrays. Closes #5295 [nov@yo.rim.or.jp].  Example:
 
     {1 => "one", 2 => "two", 3 => "three"}.sort_by(&:first).map(&:last)
-    #=> ["one", "two", "three"]
+    # => ["one", "two", "three"]
 
 * Added Hash.create_from_xml(string) which will create a hash from a XML string and even typecast if possible [David Heinemeier Hansson]. Example:
 
@@ -952,9 +957,9 @@ public for compatibility.  [Jeremy Kemper]
         <created-at type="date">2004-10-10</created-at>
       </note>
     EOT
-  
+
   ...would return:
-  
+
     { :note => { :title => "This is a note", :created_at => Date.new(2004, 10, 10) } }
 
 * Added Jim Weirich's excellent FlexMock class to vendor (Copyright 2003, 2004 by Jim Weirich (jim@weriichhouse.org)) -- it's not automatically required, though, so require 'flexmock' is still necessary [David Heinemeier Hansson]
@@ -966,28 +971,28 @@ public for compatibility.  [Jeremy Kemper]
 * Add OrderedHash#values. [Sam Stephenson]
 
 * Added Array#to_s(:db) that'll produce a comma-separated list of ids [David Heinemeier Hansson]. Example:
-    
+
     Purchase.find(:all, :conditions => "product_id IN (#{shops.products.to_s(:db)})"
 
-* Normalize classify's argument to a String so that it plays nice with Symbols. [Marcel Molina Jr.] 
+* Normalize classify's argument to a String so that it plays nice with Symbols. [Marcel Molina Jr.]
 
 * Strip out leading schema name in classify. References #5139. [Michael Schoen]
 
 * Remove Enumerable#first_match since break(value) handles the use case well enough. [Nicholas Seckar]
 
   Enumerable#first_match was like detect, but instead of returning the matching element, the yielded value returned. For example:
-  
+
     user_xml = adapters(:from => User, :to => Xml).first_match do |adapter|
       adapter.adapt @user
     end
-  
+
   But this is just as easily done with:
-  
+
     user_xml = adapters(:from => User, :to => Xml).each do
       break adapter.adapt(@user)
     end
-  
-* Make Array#in_groups_of just return the grouped collection if a block isn't given. [Marcel Molina Jr.] 
+
+* Make Array#in_groups_of just return the grouped collection if a block isn't given. [Marcel Molina Jr.]
 
 * Don't destroy a HashWithIndifferentAccess if symbolize_keys! or  stringify_keys! is called on it. Closes #5076. [Marcel Molina Jr., guy.naor@famundo.com]
 
@@ -999,7 +1004,7 @@ public for compatibility.  [Jeremy Kemper]
 
 * Replace Ruby's deprecated append_features in favor of included. [Marcel Molina Jr.]
 
-* Allow default options in with_options to be overridden. Closes #4480. [murphy@cYcnus.de] 
+* Allow default options in with_options to be overridden. Closes #4480. [murphy@cYcnus.de]
 
 * Added Module#alias_method_chain [Jamis Buck]
 
@@ -1050,7 +1055,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
 * Added Hash#to_xml and Array#to_xml that makes it much easier to produce XML from basic structures [David Heinemeier Hansson]. Examples:
 
     { :name => "David", :street_name => "Paulina", :age => 26, :moved_on => Date.new(2005, 11, 15) }.to_xml
-    
+
   ...returns:
 
       <person>
@@ -1069,7 +1074,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
 
   ex.
 
-     latest_transcripts.group_by(&:day).each do |day, transcripts| 
+     latest_transcripts.group_by(&:day).each do |day, transcripts|
        p "#{day} -> #{transcripts.map(&:class) * ', '}"
      end
      "2006-03-01 -> Transcript"
@@ -1093,7 +1098,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
 
 * Add 'around' methods to Logger,  to make it easy to log before and after messages for a given block as requested in #3809. [Michael Koziarski]  Example:
 
-  logger.around_info("Start rendering component (#{options.inspect}): ", 
+  logger.around_info("Start rendering component (#{options.inspect}): ",
                      "\n\nEnd of component rendering") { yield }
 
 * Added Time#beginning_of_quarter #3607 [cohen.jeff@gmail.com]
@@ -1111,7 +1116,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
       delegate :free?, :paying?, :to => :subscription
       delegate :overdue?, :to => "subscription.last_payment"
     end
-    
+
     account.free?    # => account.subscription.free?
     account.overdue? # => account.subscription.last_payment.overdue?
 
@@ -1126,7 +1131,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
 * Add Reloadable::Subclasses which handles the common case where a base class should not be reloaded, but its subclasses should be. [Nicholas Seckar]
 
 * Further improvements to reloading code [Nicholas Seckar, Trevor Squires]
-  
+
   - All classes/modules which include Reloadable can define reloadable? for fine grained control of reloading
   - Class.remove_class uses Module#parent to access the parent module
   - Class.remove_class expanded to handle multiple classes in a single call
@@ -1138,7 +1143,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
     class Setting
       include Reloadable
     end
-  
+
   Reloading a class is done by removing its constant which will cause it to be loaded again on the next reference. [David Heinemeier Hansson]
 
 * Added auto-loading support for classes in modules, so Conductor::Migration will look for conductor/migration.rb and Conductor::Database::Settings will look for conductor/database/settings.rb [Nicholas Seckar]
@@ -1175,7 +1180,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
 * Add Symbol#to_proc, which allows for, e.g. [:foo, :bar].map(&:to_s). [Marcel Molina Jr.]
 
 * Added the following methods [Marcel Molina Jr., Sam Stephenson]:
-  * Object#copy_instance_variables_from(object) to copy instance variables from one object to another 
+  * Object#copy_instance_variables_from(object) to copy instance variables from one object to another
   * Object#extended_by to get an instance's included/extended modules
   * Object#extend_with_included_modules_from(object) to extend an instance with the modules from another instance
 
@@ -1226,7 +1231,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
 
 *1.2.0* (October 16th, 2005)
 
-* Update Exception extension to show the first few framework frames in an application trace. [Nicholas Seckar] 
+* Update Exception extension to show the first few framework frames in an application trace. [Nicholas Seckar]
 
 * Added Exception extension to provide support for clean backtraces. [Nicholas Seckar]
 
@@ -1275,9 +1280,9 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
     Inflector.inflections do |inflect|
       inflect.plural /^(ox)$/i, '\1\2en'
       inflect.singular /^(ox)en/i, '\1'
-    
+
       inflect.irregular 'octopus', 'octopi'
-    
+
       inflect.uncountable "equipment"
     end
 
@@ -1360,9 +1365,9 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
 * Added Object#suppress which allows you to make a saner choice around with exceptions to swallow #980. Example:
 
     suppress(ZeroDivisionError) { 1/0 }
-  
+
   ...instead of:
-  
+
     1/0 rescue nil # BAD, EVIL, DIRTY.
 
 
@@ -1376,7 +1381,7 @@ approximations and shouldn't be used for critical calculations. [Michael Koziars
         values << 'baz'
       end
     end
-    
+
     foo # => ['bar', 'baz']
 
 

data/lib/active_support/base64.rb

@@ -7,7 +7,7 @@ module ActiveSupport
   if defined? ::Base64
     Base64 = ::Base64
   else
-    # Base64 provides utility methods for encoding and de-coding binary data 
+    # Base64 provides utility methods for encoding and de-coding binary data
     # using a base 64 representation. A base 64 representation of binary data
     # consists entirely of printable US-ASCII characters. The Base64 module
     # is included in Ruby 1.8, but has been removed in Ruby 1.9.
@@ -15,7 +15,7 @@ module ActiveSupport
       # Encodes a string to its base 64 representation. Each 60 characters of
       # output is separated by a newline character.
       #
-      #  ActiveSupport::Base64.encode64("Original unencoded string") 
+      #  ActiveSupport::Base64.encode64("Original unencoded string")
       #  # => "T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==\n"
       def self.encode64(data)
         [data].pack("m")
@@ -23,7 +23,7 @@ module ActiveSupport
 
       # Decodes a base 64 encoded string to its original representation.
       #
-      #  ActiveSupport::Base64.decode64("T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==") 
+      #  ActiveSupport::Base64.decode64("T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==")
       #  # => "Original unencoded string"
       def self.decode64(data)
         data.unpack("m").first

data/lib/active_support/benchmarkable.rb

@@ -3,10 +3,10 @@ require 'active_support/core_ext/hash/keys'
 
 module ActiveSupport
   module Benchmarkable
-    # Allows you to measure the execution time of a 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 
+    # 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 %>
@@ -23,7 +23,7 @@ module ActiveSupport
     #    <%= lowlevel_files_operation %>
     #  <% end %>
     #
-    # Finally, you can pass true as the third argument to silence all log activity 
+    # 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:
     #
     #  <% benchmark "Process data files", :level => :info, :silence => true do %>

data/lib/active_support/cache.rb

@@ -19,8 +19,6 @@ module ActiveSupport
     autoload :SynchronizedMemoryStore, 'active_support/cache/synchronized_memory_store'
     autoload :CompressedMemCacheStore, 'active_support/cache/compressed_mem_cache_store'
 
-    EMPTY_OPTIONS = {}.freeze
-
     # These options mean something to all cache implementations. Individual cache
     # implementations may support additional options.
     UNIVERSAL_OPTIONS = [:namespace, :compress, :compress_threshold, :expires_in, :race_condition_ttl]
@@ -129,13 +127,6 @@ module ActiveSupport
     #   cache.namespace = lambda { @last_mod_time }  # Set the namespace to a variable
     #   @last_mod_time = Time.now  # Invalidate the entire cache by changing namespace
     #
-    # All caches support auto expiring content after a specified number of seconds.
-    # To set the cache entry time to live, you can either specify +:expires_in+ as
-    # an option to the constructor to have it affect all entries or to the +fetch+
-    # or +write+ methods for just one entry.
-    #
-    #   cache = ActiveSupport::Cache::MemoryStore.new(:expire_in => 5.minutes)
-    #   cache.write(key, value, :expire_in => 1.minute)  # Set a lower value for one entry
     #
     # 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
@@ -147,7 +138,7 @@ module ActiveSupport
 
       cattr_accessor :logger, :instance_writer => true
 
-      attr_reader :silence
+      attr_reader :silence, :options
       alias :silence? :silence
 
       # Create a new cache. The options will be passed to any write method calls except
@@ -156,11 +147,6 @@ module ActiveSupport
         @options = options ? options.dup : {}
       end
 
-      # Get the default options set when the cache was created.
-      def options
-        @options ||= {}
-      end
-
       # Silence the logger.
       def silence!
         @silence = true
@@ -175,7 +161,7 @@ module ActiveSupport
         @silence = previous_silence
       end
 
-      # Set to true if cache stores should be instrumented. By default is false.
+      # Set to true if cache stores should be instrumented. Default is false.
       def self.instrument=(boolean)
         Thread.current[:instrument_cache_store] = boolean
       end
@@ -187,7 +173,7 @@ 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
+      # 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,
@@ -211,23 +197,30 @@ module ActiveSupport
       # Setting <tt>:compress</tt> will store a large cache entry set by the call
       # in a compressed format.
       #
-      # Setting <tt>:expires_in</tt> will set an expiration time on the cache
-      # entry if it is set by call.
       #
-      # Setting <tt>:race_condition_ttl</tt> will invoke logic on entries set with
-      # an <tt>:expires_in</tt> option. If an entry is found in the cache that is
-      # expired and it has been expired for less than the number of seconds specified
-      # by this option and a block was passed to the method call, then the expiration
-      # future time of the entry in the cache will be updated to that many seconds
-      # in the and the block will be evaluated and written to the cache.
+      # 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.
       #
-      # This is very useful in situations where a cache entry is used very frequently
-      # under heavy load. The first process to find an expired cache entry will then
-      # become responsible for regenerating that entry while other processes continue
-      # to use the slightly out of date entry. This can prevent race conditions where
-      # too many processes are trying to regenerate the entry all at once. If the
-      # process regenerating the entry errors out, the entry will be regenerated
-      # after the specified number of seconds.
+      #   cache = ActiveSupport::Cache::MemoryStore.new(:expire_in => 5.minutes)
+      #   cache.write(key, value, :expire_in => 1.minute)  # Set a lower value for one entry
+      #
+      # Setting <tt>:race_condition_ttl</tt> is very useful in situations where a cache entry
+      # is used very frequently unver heavy load. If a cache expires and due to heavy load
+      # seven different processes will try to read data natively and then they all will try to
+      # write to cache. To avoid that case the first process to find an expired cache entry will
+      # bump the cache expiration time by the value set in <tt>:race_condition_ttl</tt>. Yes
+      # this process is extending the time for a stale value by another few seconds. Because
+      # of extended life of the previous cache, other processes will continue to use slightly
+      # stale data for a just a big longer. In the meantime that first process will go ahead
+      # and will write into cache the new value. After that all the processes will start
+      # getting new value. The key is to keep <tt>:race_condition_ttl</tt> small.
+      #
+      # If the process regenerating the entry errors out, the entry will be regenerated
+      # after the specified number of seconds. Also note that the life of stale cache is
+      # extended only if it expired recently. Otherwise a new value is generated and
+      # <tt>:race_condition_ttl</tt> does not play any role.
       #
       #   # Set all values to expire after one minute.
       #   cache = ActiveSupport::Cache::MemoryCache.new(:expires_in => 1.minute)
@@ -252,6 +245,7 @@ module ActiveSupport
       #
       #   # val_1 => "new value 1"
       #   # val_2 => "original value"
+      #   # sleep 10 # First thread extend the life of cache by another 10 seconds
       #   # cache.fetch("foo") => "new value 1"
       #
       # Other options will be handled by the specific cache store implementation.
@@ -353,11 +347,9 @@ module ActiveSupport
         results
       end
 
-      # Writes the given value to the cache, with the given key.
+      # Writes the value to the cache, with the key.
       #
-      # You may also specify additional options via the +options+ argument.
-      # The specific cache store implementation will decide what to do with
-      # +options+.
+      # Options are passed to the underlying cache implementation.
       def write(name, value, options = nil)
         options = merged_options(options)
         instrument(:write, name, options) do |payload|
@@ -366,7 +358,7 @@ module ActiveSupport
         end
       end
 
-      # Delete an entry in the cache. Returns +true+ if there was an entry to delete.
+      # Deletes an entry in the cache. Returns +true+ if an entry is deleted.
       #
       # Options are passed to the underlying cache implementation.
       def delete(name, options = nil)
@@ -376,7 +368,7 @@ module ActiveSupport
         end
       end
 
-      # Return true if the cache contains an entry with this name.
+      # Return true if the cache contains an entry for the given key.
       #
       # Options are passed to the underlying cache implementation.
       def exist?(name, options = nil)
@@ -391,11 +383,11 @@ module ActiveSupport
         end
       end
 
-      # Delete all entries whose keys match a pattern.
+      # Delete all entries with keys matching the pattern.
       #
       # Options are passed to the underlying cache implementation.
       #
-      # Not all implementations may support +delete_matched+.
+      # All implementations may not support this method.
       def delete_matched(matcher, options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support delete_matched")
       end
@@ -404,7 +396,7 @@ module ActiveSupport
       #
       # Options are passed to the underlying cache implementation.
       #
-      # Not all implementations may support +delete_matched+.
+      # All implementations may not support this method.
       def increment(name, amount = 1, options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support increment")
       end
@@ -413,28 +405,26 @@ module ActiveSupport
       #
       # Options are passed to the underlying cache implementation.
       #
-      # Not all implementations may support +delete_matched+.
+      # All implementations may not support this method.
       def decrement(name, amount = 1, options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support decrement")
       end
 
-      # Cleanup the cache by removing expired entries. Not all cache implementations may
-      # support this method.
+      # Cleanup the cache by removing expired entries.
       #
       # Options are passed to the underlying cache implementation.
       #
-      # Not all implementations may support +delete_matched+.
+      # All implementations may not support this method.
       def cleanup(options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support cleanup")
       end
 
-      # Clear the entire cache. Not all cache implementations may support this method.
-      # You should be careful with this method since it could affect other processes
-      # if you are using a shared cache.
+      # Clear the entire cache. Be careful with this method since it could
+      # affect other processes if shared cache is being used.
       #
       # Options are passed to the underlying cache implementation.
       #
-      # Not all implementations may support +delete_matched+.
+      # All implementations may not support this method.
       def clear(options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support clear")
       end
@@ -483,9 +473,9 @@ module ActiveSupport
           end
         end
 
-        # Expand a key to be a consistent string value. If the object responds to +cache_key+,
-        # it will be called. Otherwise, the to_param method will be called. If the key is a
-        # Hash, the keys will be sorted alphabetically.
+        # Expand key to be a consistent string value. Invoke +cache_key+ if
+        # object responds to +cache_key+. Otherwise, to_param method will be
+        # called. If the key is a Hash, then keys will be sorted alphabetically.
         def expanded_key(key) # :nodoc:
           if key.respond_to?(:cache_key)
             key = key.cache_key.to_s
@@ -502,7 +492,7 @@ module ActiveSupport
           end
         end
 
-        # Prefix a key with the namespace. The two values will be delimited with a colon.
+        # Prefix a key with the namespace. Namespace and key will be delimited with a colon.
         def namespaced_key(key, options)
           key = expanded_key(key)
           namespace = options[:namespace] if options
@@ -599,7 +589,7 @@ module ActiveSupport
         end
       end
 
-      # Set a new time to live on the entry so it expires at the given time.
+      # Set a new time when the entry will expire.
       def expires_at=(time)
         if time
           @expires_in = time.to_f - @created_at
@@ -608,12 +598,12 @@ module ActiveSupport
         end
       end
 
-      # Seconds since the epoch when the cache entry will expire.
+      # Seconds since the epoch when the entry will expire.
       def expires_at
         @expires_in ? @created_at + @expires_in : nil
       end
 
-      # Get the size of the cached value. This could be less than value.size
+      # Returns the size of the cached value. This could be less than value.size
       # if the data is compressed.
       def size
         if @value.nil?