1 files changed, 12 insertions, 5 deletions
diff --git a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
index 7af10846e7..546e261cc9 100644
--- a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
@@ -1,21 +1,28 @@
 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Hash #:nodoc:
-      # Allows for reverse merging where its the keys in the calling hash that wins over those in the <tt>other_hash</tt>.
-      # This is particularly useful for initializing an incoming option hash with default values:
+      # Allows for reverse merging two hashes where the keys in the calling hash take precedence over those
+      # in the <tt>other_hash</tt>. This is particularly useful for initializing an option hash with default values:
       #
       #   def setup(options = {})
       #     options.reverse_merge! :size => 25, :velocity => 10
       #   end
       #
-      # The default <tt>:size</tt> and <tt>:velocity</tt> is only set if the +options+ passed in doesn't already have those keys set.
+      # Using <tt>merge</tt>, the above example would look as follows:
+      #
+      #   def setup(options = {})
+      #     { :size => 25, :velocity => 10 }.merge(options)
+      #   end
+      #
+      # The default <tt>:size</tt> and <tt>:velocity</tt> are only set if the +options+ hash passed in doesn't already
+      # have the respective key.
       module ReverseMerge
-        # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
+        # Performs the opposite of <tt>merge</tt>, with the keys and values from the first hash taking precedence over the second.
         def reverse_merge(other_hash)
           other_hash.merge(self)
         end
 
-        # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
+        # Performs the opposite of <tt>merge</tt>, with the keys and values from the first hash taking precedence over the second.
         # Modifies the receiver in place.
         def reverse_merge!(other_hash)
           replace(reverse_merge(other_hash))