diff --git a/hash.c b/hash.c
index 169abbd52a..f9f8077765 100644
--- a/hash.c
+++ b/hash.c
@@ -1828,12 +1828,16 @@ rb_hash_update(hash1, hash2)
* hsh.merge(other_hash){|key, oldval, newval| block} -> a_hash
*
* Returns a new hash containing the contents of other_hash and
- * the contents of hsh, overwriting entries in hsh with
- * duplicate keys with those from other_hash.
+ * the contents of hsh. If no block is specified, the value for
+ * entries with duplicate keys will be that of other_hash. Otherwise
+ * the value for 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 }
* h1.merge(h2) #=> {"a"=>100, "b"=>254, "c"=>300}
+ * h1.merge(h2){|key, oldval, newval| newval - oldval}
+ * #=> {"a"=>100, "b"=>54, "c"=>300}
* h1 #=> {"a"=>100, "b"=>200}
*
*/