hash.rb: update Hash class documents [ci skip]

mrblib/hash.rb

@@ -10,6 +10,9 @@ class Hash
   include Enumerable
 
   ##
+  # call-seq:
+  #   hash == object -> true or false
+  #
   #  Equality---Two hashes are equal if they each contain the same number
   #  of keys and if each key-value pair is equal to (according to
   #  <code>Object#==</code>) the corresponding elements in the other
@@ -30,6 +33,9 @@ class Hash
   end
 
   ##
+  # call-seq:
+  #   hash.eql? object -> true or false
+  #
   # Returns <code>true</code> if <i>hash</i> and <i>other</i> are
   # both hashes with the same content compared by eql?.
   #
@@ -48,6 +54,10 @@ class Hash
   end
 
   ##
+  # call-seq:
+  #   hash.delete(key) -> value or nil
+  #   hash.delete(key) {|key| ... } -> object
+  #
   # Delete the element with the key +key+.
   # Return the value of the element if +key+
   # was found. Return nil if nothing was
@@ -63,15 +73,14 @@ class Hash
   end
 
   ##
-  # Calls the given block for each element of +self+
-  # and pass the key and value of each element.
-  #
   # call-seq:
   #   hsh.each      {| key, value | block } -> hsh
   #   hsh.each_pair {| key, value | block } -> hsh
   #   hsh.each                              -> an_enumerator
   #   hsh.each_pair                         -> an_enumerator
   #
+  # Calls the given block for each element of +self+
+  # and pass the key and value of each element.
   #
   # If no block is given, an enumerator is returned instead.
   #
@@ -99,13 +108,13 @@ class Hash
   end
 
   ##
-  # Calls the given block for each element of +self+
-  # and pass the key of each element.
-  #
   # call-seq:
   #   hsh.each_key {| key | block } -> hsh
   #   hsh.each_key                  -> an_enumerator
   #
+  # Calls the given block for each element of +self+
+  # and pass the key of each element.
+  #
   # If no block is given, an enumerator is returned instead.
   #
   #   h = { "a" => 100, "b" => 200 }
@@ -125,13 +134,12 @@ class Hash
   end
 
   ##
-  # Calls the given block for each element of +self+
-  # and pass the value of each element.
-  #
   # call-seq:
-  #   hsh.each_value {| value | block } -> hsh
+  #   hsh.each_value {| value | block } -> self
   #   hsh.each_value                    -> an_enumerator
   #
+  # Calls the given block with each value; returns +self+:
+  #
   # If no block is given, an enumerator is returned instead.
   #
   #  h = { "a" => 100, "b" => 200 }
@@ -151,11 +159,26 @@ class Hash
   end
 
   ##
-  # Return a hash which contains the content of
-  # +self+ and +other+. If a block is given
-  # it will be called for each element with
-  # a duplicate key. The value of the block
-  # will be the final value of this element.
+  # call-seq:
+  #     hsh.merge(other_hash..)                                 -> hsh
+  #     hsh.merge(other_hash..){|key, oldval, newval| block}    -> hsh
+  #
+  #  Returns the new \Hash formed by merging each of +other_hashes+
+  #  into a copy of +self+.
+  #
+  #  Each argument in +other_hashes+ must be a \Hash.
+  #  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_.
+  #
+  #  Example:
+  #   h = {foo: 0, bar: 1, baz: 2}
+  #   h1 = {bat: 3, bar: 4}
+  #   h2 = {bam: 5, bat:6}
+  #   h3 = h.merge(h1, h2) { |key, old_value, new_value| old_value + new_value }
+  #   h3 # => {:foo=>0, :bar=>5, :baz=>2, :bat=>9, :bam=>5}
   #
   # ISO 15.2.13.4.22
   def merge(*others, &block)