From 1290747cfbaee88fa330b46613a4a8e498733436 Mon Sep 17 00:00:00 2001
From: zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Tue, 1 Jan 2013 17:17:28 +0000
Subject: [PATCH] * hash.c (rb_hash_update): Documentation for Hash#merge and
 shallow   copies Patch by Yorick Peterse [Fixes Github #228]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38672 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog |  5 +++++
 hash.c    | 23 ++++++++++++++++++-----
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5ac1c8799b..da2e4119d4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Wed Jan 02 02:16:00 2012  Zachary Scott  <zachary@zacharyscott.net>
+
+	* hash.c (rb_hash_update): Documentation for Hash#merge and shallow
+	  copies Patch by Yorick Peterse [Fixes Github #228]
+
 Mon Dec 31 15:10:00 2012  Zachary Scott  <zachary@zacharyscott.net>
 
 	* vm_backtrace.c: Add documentation for Kernel#caller_locations,
diff --git a/hash.c b/hash.c
index 34fbbf7035..976a57ee0d 100644
--- a/hash.c
+++ b/hash.c
@@ -1879,11 +1879,11 @@ rb_hash_update_block_i(VALUE key, VALUE value, VALUE hash)
  *     hsh.merge!(other_hash){|key, oldval, newval| block}    -> hsh
  *     hsh.update(other_hash){|key, oldval, newval| block}    -> hsh
  *
- *  Adds the contents of <i>other_hash</i> to <i>hsh</i>.  If no
- *  block is specified, entries with duplicate keys are overwritten
- *  with the values from <i>other_hash</i>, otherwise the value
- *  of each duplicate key is determined by calling the block with
- *  the key, its value in <i>hsh</i> and its value in <i>other_hash</i>.
+ *  Adds the contents of _other_hash_ to _hsh_.  If no block is specified,
+ *  entries with duplicate keys are overwritten with the values from
+ *  _other_hash_, otherwise the value of each duplicate key is determined by
+ *  calling the block with the key, its value in _hsh_ and its value in
+ *  _other_hash_.
  *
  *     h1 = { "a" => 100, "b" => 200 }
  *     h2 = { "b" => 254, "c" => 300 }
@@ -1893,6 +1893,19 @@ rb_hash_update_block_i(VALUE key, VALUE value, VALUE hash)
  *     h2 = { "b" => 254, "c" => 300 }
  *     h1.merge!(h2) { |key, v1, v2| v1 }
  *                     #=> {"a"=>100, "b"=>200, "c"=>300}
+ *
+ *  Note that this method creates a shallow copy of the value in _other_hash_.
+ *  This means that when for example Array#select! is used on one of the values
+ *  in _other_hash_ both the original object as well as the copy will be
+ *  modified. This is illustrated in the following example:
+ *
+ *    original = { "numbers" => [10, 20, 30] }
+ *    copy     = {}.merge(original)
+ *
+ *    copy["numbers"].select! { |number| number <= 20 }
+ *
+ *    puts copy     # => { "numbers" => [10, 20] }
+ *    puts original # => { "numbers" => [10, 20] }
  */
 
 static VALUE