From b2f73c40b8a995ed685fc76f2df724b15ead16b6 Mon Sep 17 00:00:00 2001
From: Francesco Rodriguez <lrodriguezsanc@gmail.com>
Date: Tue, 15 May 2012 10:00:09 -0500
Subject: Backporting some docs on core_ext/hash

---
 activesupport/lib/active_support/core_ext/hash/deep_dup.rb   |  7 +++++++
 activesupport/lib/active_support/core_ext/hash/deep_merge.rb |  9 +++++++--
 activesupport/lib/active_support/core_ext/hash/keys.rb       | 11 +++++++++--
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/activesupport/lib/active_support/core_ext/hash/deep_dup.rb b/activesupport/lib/active_support/core_ext/hash/deep_dup.rb
index 447142605c..c668678ce2 100644
--- a/activesupport/lib/active_support/core_ext/hash/deep_dup.rb
+++ b/activesupport/lib/active_support/core_ext/hash/deep_dup.rb
@@ -1,5 +1,12 @@
 class Hash
   # Returns a deep copy of hash.
+  #
+  #   hash = { :a => { :b => 'b' } }
+  #   dup  = hash.deep_dup
+  #   dup[:a][:c] = 'c'
+  #
+  #   hash[:a][:c] #=> nil
+  #   dup[:a][:c]  #=> "c"
   def deep_dup
     duplicate = self.dup
     duplicate.each_pair do |k,v|
diff --git a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
index af771c86ff..4f61c38eb1 100644
--- a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
@@ -1,11 +1,16 @@
 class Hash
   # Returns a new hash with +self+ and +other_hash+ merged recursively.
+  #
+  #   h1 = {:x => {:y => [4,5,6]}, :z => [7,8,9]}
+  #   h2 = {:x => {:y => [7,8,9]}, :z => "xyz"}
+  #
+  #   h1.deep_merge(h2) #=> { :x => {:y => [7, 8, 9]}, :z => "xyz" }
+  #   h2.deep_merge(h1) #=> { :x => {:y => [4, 5, 6]}, :z => [7, 8, 9] }
   def deep_merge(other_hash)
     dup.deep_merge!(other_hash)
   end
 
-  # Returns a new hash with +self+ and +other_hash+ merged recursively.
-  # Modifies the receiver in place.
+  # Same as +deep_merge+, but modifies +self+.
   def deep_merge!(other_hash)
     other_hash.each_pair do |k,v|
       tv = self[k]
diff --git a/activesupport/lib/active_support/core_ext/hash/keys.rb b/activesupport/lib/active_support/core_ext/hash/keys.rb
index d8748b1138..6b7f24eb3e 100644
--- a/activesupport/lib/active_support/core_ext/hash/keys.rb
+++ b/activesupport/lib/active_support/core_ext/hash/keys.rb
@@ -1,10 +1,14 @@
 class Hash
   # Return a new hash with all keys converted to strings.
+  #
+  #   { :name => 'Rob', :years => '28' }.stringify_keys
+  #   #=> { "name" => "Rob", "years" => "28" }
   def stringify_keys
     dup.stringify_keys!
   end
 
-  # Destructively convert all keys to strings.
+  # Destructively convert all keys to strings. Same as
+  # +stringify_keys+, but modifies +self+.
   def stringify_keys!
     keys.each do |key|
       self[key.to_s] = delete(key)
@@ -14,12 +18,15 @@ class Hash
 
   # Return a new hash with all keys converted to symbols, as long as
   # they respond to +to_sym+.
+  #
+  #   { 'name' => 'Rob', 'years' => '28' }.symbolize_keys
+  #   #=> { :name => "Rob", :years => "28" }
   def symbolize_keys
     dup.symbolize_keys!
   end
 
   # Destructively convert all keys to symbols, as long as they respond
-  # to +to_sym+.
+  # to +to_sym+. Same as +symbolize_keys+, but modifies +self+.
   def symbolize_keys!
     keys.each do |key|
       self[(key.to_sym rescue key) || key] = delete(key)
-- 
cgit v1.2.3