merge revision(s) 42555: [Backport #8911]

	* hash.c (rb_hash_aset): [DOC] Document key dup patch by @kachick
	  [Fixes GH-382] https://github.com/ruby/ruby/pull/382


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_0_0@42945 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 12 insertions, 5 deletions

diff --git a/hash.c b/hash.c
index a06e7a352b..7e0059a309 100644
--- a/hash.c
+++ b/hash.c
@@ -1172,17 +1172,24 @@ static NOINSERT_UPDATE_CALLBACK(hash_aset_str)
  *     hsh[key] = value        -> value
  *     hsh.store(key, value)   -> value
  *
- *  Element Assignment---Associates the value given by
- *  <i>value</i> with the key given by <i>key</i>.
- *  <i>key</i> should not have its value changed while it is in
- *  use as a key (a <code>String</code> passed as a key will be
- *  duplicated and frozen).
+ *  == Element Assignment
+ *
+ *  Associates the value given by +value+ with the key given by +key+.
  *
  *     h = { "a" => 100, "b" => 200 }
  *     h["a"] = 9
  *     h["c"] = 4
  *     h   #=> {"a"=>9, "b"=>200, "c"=>4}
  *
+ *  +key+ should not have its value changed while it is in use as a key (an
+ *  <tt>unfrozen String</tt> passed as a key will be duplicated and frozen).
+ *
+ *     a = "a"
+ *     b = "b".freeze
+ *     h = { a => 100, b => 200 }
+ *     h.key(100).equal? a #=> false
+ *     h.key(200).equal? b #=> true
+ *
  */
 
 VALUE