Add documentation for Hash#diff. Closes #9306 [tarmo]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8093 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activesupport/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Add documentation for Hash#diff. Closes #9306 [tarmo]
+
 * Add new superclass_delegating_accessors.  Similar to class inheritable attributes but with subtly different semantics. [Koz, tarmo]
 
 * Change JSON to encode %w(< > &) as 4 digit hex codes to be in compliance with the JSON spec.  Closes #9975 [josh, chuyeow, tpope]

activesupport/lib/active_support/core_ext/hash/diff.rb

@@ -2,6 +2,14 @@ module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Hash #:nodoc:
       module Diff
+        # Returns a hash that represents the difference between two hashes.
+        #
+        # Examples:
+        #
+        #   {1 => 2}.diff(1 => 2)         # => {}
+        #   {1 => 2}.diff(1 => 3)         # => {1 => 2}
+        #   {}.diff(1 => 2)               # => {1 => 2}
+        #   {1 => 2, 3 => 4}.diff(1 => 2) # => {3 => 4}
         def diff(h2)
           self.dup.delete_if { |k, v| h2[k] == v }.merge(h2.dup.delete_if { |k, v| self.has_key?(k) })
         end