rbs 2.0.0 → 2.2.2

data/core/hash.rbs

@@ -1,73 +1,231 @@
-# A Hash is a dictionary-like collection of unique keys and their values. Also
-# called associative arrays, they are similar to Arrays, but where an Array uses
-# integers as its index, a Hash allows you to use any object type.
+# <!-- rdoc-file=hash.c -->
+# A Hash maps each of its unique keys to a specific value.
 #
-# Hashes enumerate their values in the order that the corresponding keys were
-# inserted.
+# A Hash has certain similarities to an Array, but:
+# *   An Array index is always an Integer.
+# *   A Hash key can be (almost) any object.
 #
-# A Hash can be easily created by using its implicit form:
 #
-#     grades = { "Jane Doe" => 10, "Jim Doe" => 6 }
+# ### Hash Data Syntax
 #
-# Hashes allow an alternate syntax for keys that are symbols. Instead of
+# The older syntax for Hash data uses the "hash rocket," `=>`:
 #
-#     options = { :font_size => 10, :font_family => "Arial" }
+#     h = {:foo => 0, :bar => 1, :baz => 2}
+#     h # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# You could write it as:
+# Alternatively, but only for a Hash key that's a Symbol, you can use a newer
+# JSON-style syntax, where each bareword becomes a Symbol:
 #
-#     options = { font_size: 10, font_family: "Arial" }
+#     h = {foo: 0, bar: 1, baz: 2}
+#     h # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# Each named key is a symbol you can access in hash:
+# You can also use a String in place of a bareword:
 #
-#     options[:font_size]  # => 10
+#     h = {'foo': 0, 'bar': 1, 'baz': 2}
+#     h # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# A Hash can also be created through its ::new method:
+# And you can mix the styles:
 #
-#     grades = Hash.new
-#     grades["Dorothy Doe"] = 9
+#     h = {foo: 0, :bar => 1, 'baz': 2}
+#     h # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# Hashes have a *default value* that is returned when accessing keys that do not
-# exist in the hash. If no default is set `nil` is used. You can set the default
-# value by sending it as an argument to Hash.new:
+# But it's an error to try the JSON-style syntax for a key that's not a bareword
+# or a String:
 #
-#     grades = Hash.new(0)
+#     # Raises SyntaxError (syntax error, unexpected ':', expecting =>):
+#     h = {0: 'zero'}
 #
-# Or by using the #default= method:
+# Hash value can be omitted, meaning that value will be fetched from the context
+# by the name of the key:
 #
-#     grades = {"Timmy Doe" => 8}
-#     grades.default = 0
+#     x = 0
+#     y = 100
+#     h = {x:, y:}
+#     h # => {:x=>0, :y=>100}
 #
-# Accessing a value in a Hash requires using its key:
+# ### Common Uses
 #
-#     puts grades["Jane Doe"] # => 0
+# You can use a Hash to give names to objects:
 #
-# ### Common Uses
+#     person = {name: 'Matz', language: 'Ruby'}
+#     person # => {:name=>"Matz", :language=>"Ruby"}
 #
-# Hashes are an easy way to represent data structures, such as
+# You can use a Hash to give names to method arguments:
 #
-#     books         = {}
-#     books[:matz]  = "The Ruby Programming Language"
-#     books[:black] = "The Well-Grounded Rubyist"
+#     def some_method(hash)
+#       p hash
+#     end
+#     some_method({foo: 0, bar: 1, baz: 2}) # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# Hashes are also commonly used as a way to have named parameters in functions.
-# Note that no brackets are used below. If a hash is the last argument on a
-# method call, no braces are needed, thus creating a really clean interface:
+# Note: when the last argument in a method call is a Hash, the curly braces may
+# be omitted:
 #
-#     Person.create(name: "John Doe", age: 27)
+#     some_method(foo: 0, bar: 1, baz: 2) # => {:foo=>0, :bar=>1, :baz=>2}
 #
-#     def self.create(params)
-#       @name = params[:name]
-#       @age  = params[:age]
+# You can use a Hash to initialize an object:
+#
+#     class Dev
+#       attr_accessor :name, :language
+#       def initialize(hash)
+#         self.name = hash[:name]
+#         self.language = hash[:language]
+#       end
 #     end
+#     matz = Dev.new(name: 'Matz', language: 'Ruby')
+#     matz # => #<Dev: @name="Matz", @language="Ruby">
+#
+# ### Creating a Hash
+#
+# You can create a Hash object explicitly with:
+#
+# *   A [hash literal](doc/syntax/literals_rdoc.html#label-Hash+Literals).
+#
+#
+# You can convert certain objects to Hashes with:
+#
+# *   Method [Hash](Kernel.html#method-i-Hash).
+#
+#
+# You can create a Hash by calling method Hash.new.
+#
+# Create an empty Hash:
+#
+#     h = Hash.new
+#     h # => {}
+#     h.class # => Hash
+#
+# You can create a Hash by calling method Hash.[].
+#
+# Create an empty Hash:
+#
+#     h = Hash[]
+#     h # => {}
+#
+# Create a Hash with initial entries:
+#
+#     h = Hash[foo: 0, bar: 1, baz: 2]
+#     h # => {:foo=>0, :bar=>1, :baz=>2}
+#
+# You can create a Hash by using its literal form (curly braces).
+#
+# Create an empty Hash:
+#
+#     h = {}
+#     h # => {}
+#
+# Create a Hash with initial entries:
+#
+#     h = {foo: 0, bar: 1, baz: 2}
+#     h # => {:foo=>0, :bar=>1, :baz=>2}
+#
+# ### Hash Value Basics
+#
+# The simplest way to retrieve a Hash value (instance method #[]):
+#
+#     h = {foo: 0, bar: 1, baz: 2}
+#     h[:foo] # => 0
+#
+# The simplest way to create or update a Hash value (instance method #[]=):
+#
+#     h = {foo: 0, bar: 1, baz: 2}
+#     h[:bat] = 3 # => 3
+#     h # => {:foo=>0, :bar=>1, :baz=>2, :bat=>3}
+#     h[:foo] = 4 # => 4
+#     h # => {:foo=>4, :bar=>1, :baz=>2, :bat=>3}
+#
+# The simplest way to delete a Hash entry (instance method #delete):
+#
+#     h = {foo: 0, bar: 1, baz: 2}
+#     h.delete(:bar) # => 1
+#     h # => {:foo=>0, :baz=>2}
+#
+# ### Entry Order
+#
+# A Hash object presents its entries in the order of their creation. This is
+# seen in:
+#
+# *   Iterative methods such as `each`, `each_key`, `each_pair`, `each_value`.
+# *   Other order-sensitive methods such as `shift`, `keys`, `values`.
+# *   The String returned by method `inspect`.
+#
+#
+# A new Hash has its initial ordering per the given entries:
+#
+#     h = Hash[foo: 0, bar: 1]
+#     h # => {:foo=>0, :bar=>1}
+#
+# New entries are added at the end:
+#
+#     h[:baz] = 2
+#     h # => {:foo=>0, :bar=>1, :baz=>2}
+#
+# Updating a value does not affect the order:
+#
+#     h[:baz] = 3
+#     h # => {:foo=>0, :bar=>1, :baz=>3}
+#
+# But re-creating a deleted entry can affect the order:
+#
+#     h.delete(:foo)
+#     h[:foo] = 5
+#     h # => {:bar=>1, :baz=>3, :foo=>5}
 #
 # ### Hash Keys
 #
-# Two objects refer to the same hash key when their `hash` value is identical
-# and the two objects are `eql?` to each other.
+# #### Hash Key Equivalence
+#
+# Two objects are treated as the same hash key when their `hash` value is
+# identical and the two objects are `eql?` to each other.
+#
+# #### Modifying an Active Hash Key
+#
+# Modifying a Hash key while it is in use damages the hash's index.
+#
+# This Hash has keys that are Arrays:
+#
+#     a0 = [ :foo, :bar ]
+#     a1 = [ :baz, :bat ]
+#     h = {a0 => 0, a1 => 1}
+#     h.include?(a0) # => true
+#     h[a0] # => 0
+#     a0.hash # => 110002110
 #
-# A user-defined class may be used as a hash key if the `hash` and `eql?`
-# methods are overridden to provide meaningful behavior.  By default, separate
-# instances refer to separate hash keys.
+# Modifying array element `a0[0]` changes its hash value:
+#
+#     a0[0] = :bam
+#     a0.hash # => 1069447059
+#
+# And damages the Hash index:
+#
+#     h.include?(a0) # => false
+#     h[a0] # => nil
+#
+# You can repair the hash index using method `rehash`:
+#
+#     h.rehash # => {[:bam, :bar]=>0, [:baz, :bat]=>1}
+#     h.include?(a0) # => true
+#     h[a0] # => 0
+#
+# A String key is always safe. That's because an unfrozen String passed as a key
+# will be replaced by a duplicated and frozen String:
+#
+#     s = 'foo'
+#     s.frozen? # => false
+#     h = {s => 0}
+#     first_key = h.keys.first
+#     first_key.frozen? # => true
+#
+# #### User-Defined Hash Keys
+#
+# To be useable as a Hash key, objects must implement the methods `hash` and
+# `eql?`. Note: this requirement does not apply if the Hash uses
+# #compare_by_identity since comparison will then rely on the keys' object id
+# instead of `hash` and `eql?`.
+#
+# Object defines basic implementation for `hash` and `eq?` that makes each
+# object a distinct key. Typically, user-defined classes will want to override
+# these methods to provide meaningful behavior, or for example inherit Struct
+# that has useful definitions for these.
 #
 # A typical implementation of `hash` is based on the object's data while `eql?`
 # is usually aliased to the overridden `==` method:
@@ -81,8 +239,8 @@
 #       end
 #
 #       def ==(other)
-#         self.class === other and
-#           other.author == @author and
+#         self.class === other &&
+#           other.author == @author &&
 #           other.title == @title
 #       end
 #
@@ -103,933 +261,1708 @@
 #
 #     reviews.length #=> 1
 #
-# See also Object#hash and Object#eql?
+# ### Default Values
+#
+# The methods #[], #values_at and #dig need to return the value associated to a
+# certain key. When that key is not found, that value will be determined by its
+# default proc (if any) or else its default (initially `nil`).
+#
+# You can retrieve the default value with method #default:
+#
+#     h = Hash.new
+#     h.default # => nil
+#
+# You can set the default value by passing an argument to method Hash.new or
+# with method #default=
+#
+#     h = Hash.new(-1)
+#     h.default # => -1
+#     h.default = 0
+#     h.default # => 0
+#
+# This default value is returned for #[], #values_at and #dig when a key is not
+# found:
+#
+#     counts = {foo: 42}
+#     counts.default # => nil (default)
+#     counts[:foo] = 42
+#     counts[:bar] # => nil
+#     counts.default = 0
+#     counts[:bar] # => 0
+#     counts.values_at(:foo, :bar, :baz) # => [42, 0, 0]
+#     counts.dig(:bar) # => 0
+#
+# Note that the default value is used without being duplicated. It is not
+# advised to set the default value to a mutable object:
+#
+#     synonyms = Hash.new([])
+#     synonyms[:hello] # => []
+#     synonyms[:hello] << :hi # => [:hi], but this mutates the default!
+#     synonyms.default # => [:hi]
+#     synonyms[:world] << :universe
+#     synonyms[:world] # => [:hi, :universe], oops
+#     synonyms.keys # => [], oops
+#
+# To use a mutable object as default, it is recommended to use a default proc
+#
+# #### Default Proc
+#
+# When the default proc for a Hash is set (i.e., not `nil`), the default value
+# returned by method #[] is determined by the default proc alone.
+#
+# You can retrieve the default proc with method #default_proc:
+#
+#     h = Hash.new
+#     h.default_proc # => nil
+#
+# You can set the default proc by calling Hash.new with a block or calling the
+# method #default_proc=
+#
+#     h = Hash.new { |hash, key| "Default value for #{key}" }
+#     h.default_proc.class # => Proc
+#     h.default_proc = proc { |hash, key| "Default value for #{key.inspect}" }
+#     h.default_proc.class # => Proc
+#
+# When the default proc is set (i.e., not `nil`) and method #[] is called with
+# with a non-existent key, #[] calls the default proc with both the Hash object
+# itself and the missing key, then returns the proc's return value:
+#
+#     h = Hash.new { |hash, key| "Default value for #{key}" }
+#     h[:nosuch] # => "Default value for nosuch"
+#
+# Note that in the example above no entry for key `:nosuch` is created:
+#
+#     h.include?(:nosuch) # => false
+#
+# However, the proc itself can add a new entry:
+#
+#     synonyms = Hash.new { |hash, key| hash[key] = [] }
+#     synonyms.include?(:hello) # => false
+#     synonyms[:hello] << :hi # => [:hi]
+#     synonyms[:world] << :universe # => [:universe]
+#     synonyms.keys # => [:hello, :world]
+#
+# Note that setting the default proc will clear the default value and vice
+# versa.
+#
+# ### What's Here
+#
+# First, what's elsewhere. Class Hash:
+#
+# *   Inherits from [class
+#     Object](Object.html#class-Object-label-What-27s+Here).
+# *   Includes [module
+#     Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here), which
+#     provides dozens of additional methods.
+#
+#
+# Here, class Hash provides methods that are useful for:
+#
+# *   [Creating a Hash](#class-Hash-label-Methods+for+Creating+a+Hash)
+# *   [Setting Hash State](#class-Hash-label-Methods+for+Setting+Hash+State)
+# *   [Querying](#class-Hash-label-Methods+for+Querying)
+# *   [Comparing](#class-Hash-label-Methods+for+Comparing)
+# *   [Fetching](#class-Hash-label-Methods+for+Fetching)
+# *   [Assigning](#class-Hash-label-Methods+for+Assigning)
+# *   [Deleting](#class-Hash-label-Methods+for+Deleting)
+# *   [Iterating](#class-Hash-label-Methods+for+Iterating)
+# *   [Converting](#class-Hash-label-Methods+for+Converting)
+# *   [Transforming Keys and
+#     Values](#class-Hash-label-Methods+for+Transforming+Keys+and+Values)
+# *   [And more....](#class-Hash-label-Other+Methods)
+#
+#
+# Class Hash also includes methods from module Enumerable.
+#
+# #### Methods for Creating a Hash
+#
+# ::[]
+# :   Returns a new hash populated with given objects.
+# ::new
+# :   Returns a new empty hash.
+# ::try_convert
+# :   Returns a new hash created from a given object.
+#
+#
+# #### Methods for Setting Hash State
+#
+# #compare_by_identity
+# :   Sets `self` to consider only identity in comparing keys.
+# #default=
+# :   Sets the default to a given value.
+# #default_proc=
+# :   Sets the default proc to a given proc.
+# #rehash
+# :   Rebuilds the hash table by recomputing the hash index for each key.
+#
+#
+# #### Methods for Querying
+#
+# #any?
+# :   Returns whether any element satisfies a given criterion.
+# #compare_by_identity?
+# :   Returns whether the hash considers only identity when comparing keys.
+# #default
+# :   Returns the default value, or the default value for a given key.
+# #default_proc
+# :   Returns the default proc.
+# #empty?
+# :   Returns whether there are no entries.
+# #eql?
+# :   Returns whether a given object is equal to `self`.
+# #hash
+# :   Returns the integer hash code.
+# #has_value?
+# :   Returns whether a given object is a value in `self`.
+# #include?, #has_key?, #member?, #key?
+# :   Returns whether a given object is a key in `self`.
+# #length, #size
+# :   Returns the count of entries.
+# #value?
+# :   Returns whether a given object is a value in `self`.
+#
+#
+# #### Methods for Comparing
+#
+# [#<](#method-i-3C)
+# :   Returns whether `self` is a proper subset of a given object.
+# [#<=](#method-i-3C-3D)
+# :   Returns whether `self` is a subset of a given object.
+# [#==](#method-i-3D-3D)
+# :   Returns whether a given object is equal to `self`.
+# [#>](#method-i-3E)
+# :   Returns whether `self` is a proper superset of a given object
+# [#>=](#method-i-3E-3D)
+# :   Returns whether `self` is a proper superset of a given object.
+#
+#
+# #### Methods for Fetching
+#
+# #[]
+# :   Returns the value associated with a given key.
+# #assoc
+# :   Returns a 2-element array containing a given key and its value.
+# #dig
+# :   Returns the object in nested objects that is specified by a given key and
+#     additional arguments.
+# #fetch
+# :   Returns the value for a given key.
+# #fetch_values
+# :   Returns array containing the values associated with given keys.
+# #key
+# :   Returns the key for the first-found entry with a given value.
+# #keys
+# :   Returns an array containing all keys in `self`.
+# #rassoc
+# :   Returns a 2-element array consisting of the key and value of the
+#     first-found entry having a given value.
+# #values
+# :   Returns an array containing all values in `self`/
+# #values_at
+# :   Returns an array containing values for given keys.
+#
+#
+# #### Methods for Assigning
+#
+# #[]=, #store
+# :   Associates a given key with a given value.
+# #merge
+# :   Returns the hash formed by merging each given hash into a copy of `self`.
+# #merge!, #update
+# :   Merges each given hash into `self`.
+# #replace
+# :   Replaces the entire contents of `self` with the contents of a givan hash.
+#
+#
+# #### Methods for Deleting
+#
+# These methods remove entries from `self`:
+#
+# #clear
+# :   Removes all entries from `self`.
+# #compact!
+# :   Removes all `nil`-valued entries from `self`.
+# #delete
+# :   Removes the entry for a given key.
+# #delete_if
+# :   Removes entries selected by a given block.
+# #filter!, #select!
+# :   Keep only those entries selected by a given block.
+# #keep_if
+# :   Keep only those entries selected by a given block.
+# #reject!
+# :   Removes entries selected by a given block.
+# #shift
+# :   Removes and returns the first entry.
+#
+#
+# These methods return a copy of `self` with some entries removed:
+#
+# #compact
+# :   Returns a copy of `self` with all `nil`-valued entries removed.
+# #except
+# :   Returns a copy of `self` with entries removed for specified keys.
+# #filter, #select
+# :   Returns a copy of `self` with only those entries selected by a given
+#     block.
+# #reject
+# :   Returns a copy of `self` with entries removed as specified by a given
+#     block.
+# #slice
+# :   Returns a hash containing the entries for given keys.
+#
+#
+# #### Methods for Iterating
+# #each, #each_pair
+# :   Calls a given block with each key-value pair.
+# #each_key
+# :   Calls a given block with each key.
+# #each_value
+# :   Calls a given block with each value.
+#
+#
+# #### Methods for Converting
+#
+# #inspect, #to_s
+# :   Returns a new String containing the hash entries.
+# #to_a
+# :   Returns a new array of 2-element arrays; each nested array contains a
+#     key-value pair from `self`.
+# #to_h
+# :   Returns `self` if a Hash; if a subclass of Hash, returns a Hash containing
+#     the entries from `self`.
+# #to_hash
+# :   Returns `self`.
+# #to_proc
+# :   Returns a proc that maps a given key to its value.
+#
+#
+# #### Methods for Transforming Keys and Values
+#
+# #transform_keys
+# :   Returns a copy of `self` with modified keys.
+# #transform_keys!
+# :   Modifies keys in `self`
+# #transform_values
+# :   Returns a copy of `self` with modified values.
+# #transform_values!
+# :   Modifies values in `self`.
+#
+#
+# #### Other Methods
+# #flatten
+# :   Returns an array that is a 1-dimensional flattening of `self`.
+# #invert
+# :   Returns a hash with the each key-value pair inverted.
 #
 class Hash[unchecked out K, unchecked out V] < Object
-  include Enumerable[[K, V]]
+  include Enumerable[[ K, V ]]
 
-  # Creates a new hash populated with the given objects.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - Hash[] -> new_empty_hash
+  #   - Hash[hash] -> new_hash
+  #   - Hash[ [*2_element_arrays] ] -> new_hash
+  #   - Hash[*objects] -> new_hash
+  # -->
+  # Returns a new Hash object populated with the given objects, if any. See
+  # Hash::new.
+  #
+  # With no argument, returns a new empty Hash.
+  #
+  # When the single given argument is a Hash, returns a new Hash populated with
+  # the entries from the given Hash, excluding the default value or proc.
+  #
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     Hash[h] # => {:foo=>0, :bar=>1, :baz=>2}
+  #
+  # When the single given argument is an Array of 2-element Arrays, returns a new
+  # Hash object wherein each 2-element array forms a key-value entry:
+  #
+  #     Hash[ [ [:foo, 0], [:bar, 1] ] ] # => {:foo=>0, :bar=>1}
   #
-  # Similar to the literal `{ *key* => *value*, ... }`. In the first form, keys
-  # and values occur in pairs, so there must be an even number of arguments.
+  # When the argument count is an even number; returns a new Hash object wherein
+  # each successive pair of arguments has become a key-value entry:
   #
-  # The second and third form take a single argument which is either an array of
-  # key-value pairs or an object convertible to a hash.
+  #     Hash[:foo, 0, :bar, 1] # => {:foo=>0, :bar=>1}
   #
-  #     Hash["a", 100, "b", 200]             #=> {"a"=>100, "b"=>200}
-  #     Hash[ [ ["a", 100], ["b", 200] ] ]   #=> {"a"=>100, "b"=>200}
-  #     Hash["a" => 100, "b" => 200]         #=> {"a"=>100, "b"=>200}
+  # Raises an exception if the argument list does not conform to any of the above.
   #
   def self.[]: [U, V] (_ToHash[U, V]) -> ::Hash[U, V]
              | [U, V] (Array[[ U, V ]]) -> ::Hash[U, V]
              | (*untyped) -> ::Hash[untyped, untyped]
 
-  # Try to convert *obj* into a hash, using to_hash method. Returns converted hash
-  # or nil if *obj* cannot be converted for any reason.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - Hash.try_convert(obj) -> obj, new_hash, or nil
+  # -->
+  # If `obj` is a Hash object, returns `obj`.
   #
-  #     Hash.try_convert({1=>2})   # => {1=>2}
-  #     Hash.try_convert("1=>2")   # => nil
+  # Otherwise if `obj` responds to `:to_hash`, calls `obj.to_hash` and returns the
+  # result.
+  #
+  # Returns `nil` if `obj` does not respond to `:to_hash`
+  #
+  # Raises an exception unless `obj.to_hash` returns a Hash object.
   #
   def self.try_convert: [U, V] (_ToHash[U, V]) -> ::Hash[U, V]
                       | (untyped) -> (::Hash[untyped, untyped] | nil)
 
   public
 
-  # Returns `true` if *hash* is subset of *other*.
-  #
-  #     h1 = {a:1, b:2}
-  #     h2 = {a:1, b:2, c:3}
-  #     h1 < h2    #=> true
-  #     h2 < h1    #=> false
-  #     h1 < h1    #=> false
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash < other_hash -> true or false
+  # -->
+  # Returns `true` if `hash` is a proper subset of `other_hash`, `false`
+  # otherwise:
+  #     h1 = {foo: 0, bar: 1}
+  #     h2 = {foo: 0, bar: 1, baz: 2}
+  #     h1 < h2 # => true
+  #     h2 < h1 # => false
+  #     h1 < h1 # => false
   #
   def <: [A, B] (::Hash[A, B]) -> bool
 
-  # Returns `true` if *hash* is subset of *other* or equals to *other*.
-  #
-  #     h1 = {a:1, b:2}
-  #     h2 = {a:1, b:2, c:3}
-  #     h1 <= h2   #=> true
-  #     h2 <= h1   #=> false
-  #     h1 <= h1   #=> true
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash <= other_hash -> true or false
+  # -->
+  # Returns `true` if `hash` is a subset of `other_hash`, `false` otherwise:
+  #     h1 = {foo: 0, bar: 1}
+  #     h2 = {foo: 0, bar: 1, baz: 2}
+  #     h1 <= h2 # => true
+  #     h2 <= h1 # => false
+  #     h1 <= h1 # => true
   #
   def <=: [A, B] (::Hash[A, B]) -> bool
 
-  # 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 Object#==) the
-  # corresponding elements in the other hash.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash == object -> true or false
+  # -->
+  # Returns `true` if all of the following are true:
+  # *   `object` is a Hash object.
+  # *   `hash` and `object` have the same keys (regardless of order).
+  # *   For each key `key`, `hash[key] == object[key]`.
   #
-  #     h1 = { "a" => 1, "c" => 2 }
-  #     h2 = { 7 => 35, "c" => 2, "a" => 1 }
-  #     h3 = { "a" => 1, "c" => 2, 7 => 35 }
-  #     h4 = { "a" => 1, "d" => 2, "f" => 35 }
-  #     h1 == h2   #=> false
-  #     h2 == h3   #=> true
-  #     h3 == h4   #=> false
   #
-  # The orders of each hashes are not compared.
+  # Otherwise, returns `false`.
   #
-  #     h1 = { "a" => 1, "c" => 2 }
-  #     h2 = { "c" => 2, "a" => 1 }
-  #     h1 == h2   #=> true
+  # Equal:
+  #     h1 = {foo: 0, bar: 1, baz: 2}
+  #     h2 = {foo: 0, bar: 1, baz: 2}
+  #     h1 == h2 # => true
+  #     h3 = {baz: 2, bar: 1, foo: 0}
+  #     h1 == h3 # => true
   #
   def ==: (untyped other) -> bool
 
-  # Returns `true` if *other* is subset of *hash*.
-  #
-  #     h1 = {a:1, b:2}
-  #     h2 = {a:1, b:2, c:3}
-  #     h1 > h2    #=> false
-  #     h2 > h1    #=> true
-  #     h1 > h1    #=> false
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash > other_hash -> true or false
+  # -->
+  # Returns `true` if `hash` is a proper superset of `other_hash`, `false`
+  # otherwise:
+  #     h1 = {foo: 0, bar: 1, baz: 2}
+  #     h2 = {foo: 0, bar: 1}
+  #     h1 > h2 # => true
+  #     h2 > h1 # => false
+  #     h1 > h1 # => false
   #
   def >: [A, B] (::Hash[A, B]) -> bool
 
-  # Returns `true` if *other* is subset of *hash* or equals to *hash*.
-  #
-  #     h1 = {a:1, b:2}
-  #     h2 = {a:1, b:2, c:3}
-  #     h1 >= h2   #=> false
-  #     h2 >= h1   #=> true
-  #     h1 >= h1   #=> true
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash >= other_hash -> true or false
+  # -->
+  # Returns `true` if `hash` is a superset of `other_hash`, `false` otherwise:
+  #     h1 = {foo: 0, bar: 1, baz: 2}
+  #     h2 = {foo: 0, bar: 1}
+  #     h1 >= h2 # => true
+  #     h2 >= h1 # => false
+  #     h1 >= h1 # => true
   #
   def >=: [A, B] (::Hash[A, B]) -> bool
 
-  # Element Reference---Retrieves the *value* object corresponding to the *key*
-  # object. If not found, returns the default value (see Hash::new for details).
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash[key] -> value
+  # -->
+  # Returns the value associated with the given `key`, if found:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h[:foo] # => 0
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h["a"]   #=> 100
-  #     h["c"]   #=> nil
+  # If `key` is not found, returns a default value (see [Default
+  # Values](#class-Hash-label-Default+Values)):
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h[:nosuch] # => nil
   #
   def []: (K arg0) -> V
 
-  # ## 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}
-  #     h.store("d", 42) #=> 42
-  #     h   #=> {"a"=>9, "b"=>200, "c"=>4, "d"=>42}
-  #
-  # `key` should not have its value changed while it is in use as a key (an
-  # `unfrozen String` 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
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash[key] = value -> value
+  #   - hash.store(key, value)
+  # -->
+  # Hash#store is an alias for Hash#[]=.
+  #
+  # Associates the given `value` with the given `key`; returns `value`.
+  #
+  # If the given `key` exists, replaces its value with the given `value`; the
+  # ordering is not affected (see [Entry Order](#class-Hash-label-Entry+Order)):
+  #     h = {foo: 0, bar: 1}
+  #     h[:foo] = 2 # => 2
+  #     h.store(:bar, 3) # => 3
+  #     h # => {:foo=>2, :bar=>3}
+  #
+  # If `key` does not exist, adds the `key` and `value`; the new entry is last in
+  # the order (see [Entry Order](#class-Hash-label-Entry+Order)):
+  #     h = {foo: 0, bar: 1}
+  #     h[:baz] = 2 # => 2
+  #     h.store(:bat, 3) # => 3
+  #     h # => {:foo=>0, :bar=>1, :baz=>2, :bat=>3}
   #
   def []=: (K arg0, V arg1) -> V
 
-  # See also Enumerable#any?
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.any? -> true or false
+  #   - hash.any?(object) -> true or false
+  #   - hash.any? {|key, value| ... } -> true or false
+  # -->
+  # Returns `true` if any element satisfies a given criterion; `false` otherwise.
+  #
+  # With no argument and no block, returns `true` if `self` is non-empty; `false`
+  # if empty.
+  #
+  # With argument `object` and no block, returns `true` if for any key `key`
+  # `h.assoc(key) == object`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.any?([:bar, 1]) # => true
+  #     h.any?([:bar, 0]) # => false
+  #     h.any?([:baz, 1]) # => false
+  #
+  # With no argument and a block, calls the block with each key-value pair;
+  # returns `true` if the block returns any truthy value, `false` otherwise:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.any? {|key, value| value < 3 } # => true
+  #     h.any? {|key, value| value > 3 } # => false
   #
   def any?: () -> bool
           | (untyped pattern) -> bool
           | () { (K, V) -> boolish } -> bool
 
-  # Searches through the hash comparing *obj* with the key using `==`. Returns the
-  # key-value pair (two elements array) or `nil` if no match is found.  See
-  # Array#assoc.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.assoc(key) -> new_array or nil
+  # -->
+  # If the given `key` is found, returns a 2-element Array containing that key and
+  # its value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.assoc(:bar) # => [:bar, 1]
   #
-  #     h = {"colors"  => ["red", "blue", "green"],
-  #          "letters" => ["a", "b", "c" ]}
-  #     h.assoc("letters")  #=> ["letters", ["a", "b", "c"]]
-  #     h.assoc("foo")      #=> nil
+  # Returns `nil` if key `key` is not found.
   #
-  def assoc: (K arg0) -> [K, V]?
+  def assoc: (K arg0) -> [ K, V ]?
 
-  # Removes all key-value pairs from *hsh*.
-  #
-  #     h = { "a" => 100, "b" => 200 }   #=> {"a"=>100, "b"=>200}
-  #     h.clear                          #=> {}
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.clear -> self
+  # -->
+  # Removes all hash entries; returns `self`.
   #
   def clear: () -> self
 
-  # Returns a new hash with the nil values/key pairs removed
-  #
-  #     h = { a: 1, b: false, c: nil }
-  #     h.compact     #=> { a: 1, b: false }
-  #     h             #=> { a: 1, b: false, c: nil }
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.compact -> new_hash
+  # -->
+  # Returns a copy of `self` with all `nil`-valued entries removed:
+  #     h = {foo: 0, bar: nil, baz: 2, bat: nil}
+  #     h1 = h.compact
+  #     h1 # => {:foo=>0, :baz=>2}
   #
   def compact: () -> ::Hash[K, V]
 
-  # Removes all nil values from the hash. Returns nil if no changes were made,
-  # otherwise returns the hash.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.compact! -> self or nil
+  # -->
+  # Returns `self` with all its `nil`-valued entries removed (in place):
+  #     h = {foo: 0, bar: nil, baz: 2, bat: nil}
+  #     h.compact! # => {:foo=>0, :baz=>2}
   #
-  #     h = { a: 1, b: false, c: nil }
-  #     h.compact!     #=> { a: 1, b: false }
+  # Returns `nil` if no entries were removed.
   #
   def compact!: () -> self?
 
-  # Makes *hsh* compare its keys by their identity, i.e. it will consider exact
-  # same objects as same keys.
-  #
-  #     h1 = { "a" => 100, "b" => 200, :c => "c" }
-  #     h1["a"]        #=> 100
-  #     h1.compare_by_identity
-  #     h1.compare_by_identity? #=> true
-  #     h1["a".dup]    #=> nil  # different objects.
-  #     h1[:c]         #=> "c"  # same symbols are all same.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.compare_by_identity -> self
+  # -->
+  # Sets `self` to consider only identity in comparing keys; two keys are
+  # considered the same only if they are the same object; returns `self`.
+  #
+  # By default, these two object are considered to be the same key, so `s1` will
+  # overwrite `s0`:
+  #     s0 = 'x'
+  #     s1 = 'x'
+  #     h = {}
+  #     h.compare_by_identity? # => false
+  #     h[s0] = 0
+  #     h[s1] = 1
+  #     h # => {"x"=>1}
+  #
+  # After calling #compare_by_identity, the keys are considered to be different,
+  # and therefore do not overwrite each other:
+  #     h = {}
+  #     h.compare_by_identity # => {}
+  #     h.compare_by_identity? # => true
+  #     h[s0] = 0
+  #     h[s1] = 1
+  #     h # => {"x"=>0, "x"=>1}
   #
   def compare_by_identity: () -> self
 
-  # Returns `true` if *hsh* will compare its keys by their identity.  Also see
-  # Hash#compare_by_identity.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.compare_by_identity? -> true or false
+  # -->
+  # Returns `true` if #compare_by_identity has been called, `false` otherwise.
   #
   def compare_by_identity?: () -> bool
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - deconstruct_keys(p1)
+  # -->
+  #
   def deconstruct_keys: (Array[K] | nil) -> self
 
-  # Returns the default value, the value that would be returned by *[hsh](key)* if
-  # *key* did not exist in *hsh*. See also Hash::new and Hash#default=.
-  #
-  #     h = Hash.new                            #=> {}
-  #     h.default                               #=> nil
-  #     h.default(2)                            #=> nil
-  #
-  #     h = Hash.new("cat")                     #=> {}
-  #     h.default                               #=> "cat"
-  #     h.default(2)                            #=> "cat"
-  #
-  #     h = Hash.new {|h,k| h[k] = k.to_i*10}   #=> {}
-  #     h.default                               #=> nil
-  #     h.default(2)                            #=> 20
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.default -> object
+  #   - hash.default(key) -> object
+  # -->
+  # Returns the default value for the given `key`. The returned value will be
+  # determined either by the default proc or by the default value. See [Default
+  # Values](#class-Hash-label-Default+Values).
+  #
+  # With no argument, returns the current default value:
+  #     h = {}
+  #     h.default # => nil
+  #
+  # If `key` is given, returns the default value for `key`, regardless of whether
+  # that key exists:
+  #     h = Hash.new { |hash, key| hash[key] = "No key #{key}"}
+  #     h[:foo] = "Hello"
+  #     h.default(:foo) # => "No key foo"
   #
   def default: (?K arg0) -> V?
 
-  # Sets the default value, the value returned for a key that does not exist in
-  # the hash. It is not possible to set the default to a Proc that will be
-  # executed on each key lookup.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.default = "Go fish"
-  #     h["a"]     #=> 100
-  #     h["z"]     #=> "Go fish"
-  #     # This doesn't do what you might hope...
-  #     h.default = proc do |hash, key|
-  #       hash[key] = key + key
-  #     end
-  #     h[2]       #=> #<Proc:0x401b3948@-:6>
-  #     h["cat"]   #=> #<Proc:0x401b3948@-:6>
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.default = value -> object
+  # -->
+  # Sets the default value to `value`; returns `value`:
+  #     h = {}
+  #     h.default # => nil
+  #     h.default = false # => false
+  #     h.default # => false
+  #
+  # See [Default Values](#class-Hash-label-Default+Values).
   #
   def default=: (V arg0) -> V
 
-  # If Hash::new was invoked with a block, return that block, otherwise return
-  # `nil`.
-  #
-  #     h = Hash.new {|h,k| h[k] = k*k }   #=> {}
-  #     p = h.default_proc                 #=> #<Proc:0x401b3d08@-:1>
-  #     a = []                             #=> []
-  #     p.call(a, 2)
-  #     a                                  #=> [nil, nil, 4]
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.default_proc -> proc or nil
+  # -->
+  # Returns the default proc for `self` (see [Default
+  # Values](#class-Hash-label-Default+Values)):
+  #     h = {}
+  #     h.default_proc # => nil
+  #     h.default_proc = proc {|hash, key| "Default value for #{key}" }
+  #     h.default_proc.class # => Proc
   #
   def default_proc: () -> (Proc | nil)
 
-  # Sets the default proc to be executed on each failed key lookup.
-  #
-  #     h.default_proc = proc do |hash, key|
-  #       hash[key] = key + key
-  #     end
-  #     h[2]       #=> 4
-  #     h["cat"]   #=> "catcat"
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.default_proc = proc -> proc
+  # -->
+  # Sets the default proc for `self` to `proc`: (see [Default
+  # Values](#class-Hash-label-Default+Values)):
+  #     h = {}
+  #     h.default_proc # => nil
+  #     h.default_proc = proc { |hash, key| "Default value for #{key}" }
+  #     h.default_proc.class # => Proc
+  #     h.default_proc = nil
+  #     h.default_proc # => nil
   #
   def default_proc=: (Proc | _ToProc | nil) -> (Proc | _ToProc | nil)
 
-  # Deletes the key-value pair and returns the value from *hsh* whose key is equal
-  # to *key*. If the key is not found, it returns *nil*. If the optional code
-  # block is given and the key is not found, pass in the key and return the result
-  # of *block*.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.delete("a")                              #=> 100
-  #     h.delete("z")                              #=> nil
-  #     h.delete("z") { |el| "#{el} not found" }   #=> "z not found"
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.delete(key) -> value or nil
+  #   - hash.delete(key) {|key| ... } -> object
+  # -->
+  # Deletes the entry for the given `key` and returns its associated value.
+  #
+  # If no block is given and `key` is found, deletes the entry and returns the
+  # associated value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.delete(:bar) # => 1
+  #     h # => {:foo=>0, :baz=>2}
+  #
+  # If no block given and `key` is not found, returns `nil`.
+  #
+  # If a block is given and `key` is found, ignores the block, deletes the entry,
+  # and returns the associated value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.delete(:baz) { |key| raise 'Will never happen'} # => 2
+  #     h # => {:foo=>0, :bar=>1}
+  #
+  # If a block is given and `key` is not found, calls the block and returns the
+  # block's return value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.delete(:nosuch) { |key| "Key #{key} not found" } # => "Key nosuch not found"
+  #     h # => {:foo=>0, :bar=>1, :baz=>2}
   #
   def delete: (K arg0) -> V?
             | [U] (K arg0) { (K arg0) -> U } -> (U | V)
 
-  # Deletes every key-value pair from *hsh* for which *block* evaluates to `true`.
-  #
-  # If no block is given, an enumerator is returned instead.
-  #
-  #     h = { "a" => 100, "b" => 200, "c" => 300 }
-  #     h.delete_if {|key, value| key >= "b" }   #=> {"a"=>100}
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.delete_if {|key, value| ... } -> self
+  #   - hash.delete_if -> new_enumerator
+  # -->
+  # If a block given, calls the block with each key-value pair; deletes each entry
+  # for which the block returns a truthy value; returns `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.delete_if {|key, value| value > 0 } # => {:foo=>0}
+  #
+  # If no block given, returns a new Enumerator:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.delete_if # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:delete_if>
+  #     e.each { |key, value| value > 0 } # => {:foo=>0}
   #
   def delete_if: () { (K, V) -> boolish } -> self
                | () -> ::Enumerator[[ K, V ], self]
 
-  # Extracts the nested value specified by the sequence of *key* objects by
-  # calling `dig` at each step, returning `nil` if any intermediate step is `nil`.
-  #
-  #     h = { foo: {bar: {baz: 1}}}
-  #
-  #     h.dig(:foo, :bar, :baz)     #=> 1
-  #     h.dig(:foo, :zot, :xyz)     #=> nil
-  #
-  #     g = { foo: [10, 11, 12] }
-  #     g.dig(:foo, 1)              #=> 11
-  #     g.dig(:foo, 1, 0)           #=> TypeError: Integer does not have #dig method
-  #     g.dig(:foo, :bar)           #=> TypeError: no implicit conversion of Symbol into Integer
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.dig(key, *identifiers) -> object
+  # -->
+  # Finds and returns the object in nested objects that is specified by `key` and
+  # `identifiers`. The nested objects may be instances of various classes. See
+  # [Dig Methods](rdoc-ref:dig_methods.rdoc).
+  #
+  # Nested Hashes:
+  #     h = {foo: {bar: {baz: 2}}}
+  #     h.dig(:foo) # => {:bar=>{:baz=>2}}
+  #     h.dig(:foo, :bar) # => {:baz=>2}
+  #     h.dig(:foo, :bar, :baz) # => 2
+  #     h.dig(:foo, :bar, :BAZ) # => nil
+  #
+  # Nested Hashes and Arrays:
+  #     h = {foo: {bar: [:a, :b, :c]}}
+  #     h.dig(:foo, :bar, 2) # => :c
+  #
+  # This method will use the [default values](#class-Hash-label-Default+Values)
+  # for keys that are not present:
+  #     h = {foo: {bar: [:a, :b, :c]}}
+  #     h.dig(:hello) # => nil
+  #     h.default_proc = -> (hash, _key) { hash }
+  #     h.dig(:hello, :world) # => h
+  #     h.dig(:hello, :world, :foo, :bar, 2) # => :c
   #
   def dig: (*untyped) -> untyped
 
-  # Calls *block* once for each key in *hsh*, passing the key-value pair as
-  # parameters.
+  # <!-- rdoc-file=hash.c -->
+  # Hash#each is an alias for Hash#each_pair.
   #
-  # If no block is given, an enumerator is returned instead.
+  # Calls the given block with each key-value pair; returns `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.each_pair {|key, value| puts "#{key}: #{value}"} # => {:foo=>0, :bar=>1, :baz=>2}
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.each {|key, value| puts "#{key} is #{value}" }
+  # Output:
+  #     foo: 0
+  #     bar: 1
+  #     baz: 2
   #
-  # *produces:*
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.each_pair # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:each_pair>
+  #     h1 = e.each {|key, value| puts "#{key}: #{value}"}
+  #     h1 # => {:foo=>0, :bar=>1, :baz=>2}
   #
-  #     a is 100
-  #     b is 200
+  # Output:
+  #     foo: 0
+  #     bar: 1
+  #     baz: 2
   #
   def each: () { ([ K, V ] arg0) -> untyped } -> self
           | () -> ::Enumerator[[ K, V ], self]
 
-  # Calls *block* once for each key in *hsh*, passing the key as a parameter.
-  #
-  # If no block is given, an enumerator is returned instead.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.each_key {|key| puts key }
-  #
-  # *produces:*
-  #
-  #     a
-  #     b
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.each_key {|key| ... } -> self
+  #   - hash.each_key -> new_enumerator
+  # -->
+  # Calls the given block with each key; returns `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.each_key {|key| puts key }  # => {:foo=>0, :bar=>1, :baz=>2}
+  #
+  # Output:
+  #     foo
+  #     bar
+  #     baz
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.each_key # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:each_key>
+  #     h1 = e.each {|key| puts key }
+  #     h1 # => {:foo=>0, :bar=>1, :baz=>2}
+  #
+  # Output:
+  #     foo
+  #     bar
+  #     baz
   #
   def each_key: () { (K arg0) -> untyped } -> ::Hash[K, V]
               | () -> ::Enumerator[K, self]
 
-  # Calls *block* once for each key in *hsh*, passing the key-value pair as
-  # parameters.
-  #
-  # If no block is given, an enumerator is returned instead.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.each {|key, value| puts "#{key} is #{value}" }
-  #
-  # *produces:*
-  #
-  #     a is 100
-  #     b is 200
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.each {|key, value| ... } -> self
+  #   - hash.each_pair {|key, value| ... } -> self
+  #   - hash.each -> new_enumerator
+  #   - hash.each_pair -> new_enumerator
+  # -->
+  # Hash#each is an alias for Hash#each_pair.
+  #
+  # Calls the given block with each key-value pair; returns `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.each_pair {|key, value| puts "#{key}: #{value}"} # => {:foo=>0, :bar=>1, :baz=>2}
+  #
+  # Output:
+  #     foo: 0
+  #     bar: 1
+  #     baz: 2
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.each_pair # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:each_pair>
+  #     h1 = e.each {|key, value| puts "#{key}: #{value}"}
+  #     h1 # => {:foo=>0, :bar=>1, :baz=>2}
+  #
+  # Output:
+  #     foo: 0
+  #     bar: 1
+  #     baz: 2
   #
   alias each_pair each
 
-  # Calls *block* once for each key in *hsh*, passing the value as a parameter.
-  #
-  # If no block is given, an enumerator is returned instead.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.each_value {|value| puts value }
-  #
-  # *produces:*
-  #
-  #     100
-  #     200
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.each_value {|value| ... } -> self
+  #   - hash.each_value -> new_enumerator
+  # -->
+  # Calls the given block with each value; returns `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.each_value {|value| puts value } # => {:foo=>0, :bar=>1, :baz=>2}
+  #
+  # Output:
+  #     0
+  #     1
+  #     2
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.each_value # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:each_value>
+  #     h1 = e.each {|value| puts value }
+  #     h1 # => {:foo=>0, :bar=>1, :baz=>2}
+  #
+  # Output:
+  #     0
+  #     1
+  #     2
   #
   def each_value: () { (V arg0) -> untyped } -> self
                 | () -> ::Enumerator[V, self]
 
-  # Returns `true` if *hsh* contains no key-value pairs.
-  #
-  #     {}.empty?   #=> true
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.empty? -> true or false
+  # -->
+  # Returns `true` if there are no hash entries, `false` otherwise:
+  #     {}.empty? # => true
+  #     {foo: 0, bar: 1, baz: 2}.empty? # => false
   #
   def empty?: () -> bool
 
-  # Returns `true` if *hash* and *other* are both hashes with the same content.
-  # The orders of each hashes are not compared.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.eql? object -> true or false
+  # -->
+  # Returns `true` if all of the following are true:
+  # *   `object` is a Hash object.
+  # *   `hash` and `object` have the same keys (regardless of order).
+  # *   For each key `key`, `h[key] eql? object[key]`.
+  #
+  #
+  # Otherwise, returns `false`.
+  #
+  # Equal:
+  #     h1 = {foo: 0, bar: 1, baz: 2}
+  #     h2 = {foo: 0, bar: 1, baz: 2}
+  #     h1.eql? h2 # => true
+  #     h3 = {baz: 2, bar: 1, foo: 0}
+  #     h1.eql? h3 # => true
   #
   def eql?: (untyped) -> bool
 
-  # Returns a hash excluded given keys and the values.
-  #
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hsh.except(*keys) -> a_hash
+  # -->
+  # Returns a new Hash excluding entries for the given `keys`:
   #     h = { a: 100, b: 200, c: 300 }
-  #     h.except(:a)           #=> {:b=>200, :c=>300}
-  #     h.except(:b, :c, :d)   #=> {:a=>100}
+  #     h.except(:a)          #=> {:b=>200, :c=>300}
+  #
+  # Any given `keys` that are not found are ignored.
   #
   def except: (*K) -> ::Hash[K, V]
 
-  # Returns a value from the hash for the given key. If the key can't be found,
-  # there are several options: With no other arguments, it will raise a KeyError
-  # exception; if *default* is given, then that will be returned; if the optional
-  # code block is specified, then that will be run and its result returned.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.fetch(key) -> object
+  #   - hash.fetch(key, default_value) -> object
+  #   - hash.fetch(key) {|key| ... } -> object
+  # -->
+  # Returns the value for the given `key`, if found.
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.fetch(:bar) # => 1
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.fetch("a")                            #=> 100
-  #     h.fetch("z", "go fish")                 #=> "go fish"
-  #     h.fetch("z") { |el| "go fish, #{el}"}   #=> "go fish, z"
+  # If `key` is not found and no block was given, returns `default_value`:
+  #     {}.fetch(:nosuch, :default) # => :default
   #
-  # The following example shows that an exception is raised if the key is not
-  # found and a default value is not supplied.
+  # If `key` is not found and a block was given, yields `key` to the block and
+  # returns the block's return value:
+  #     {}.fetch(:nosuch) {|key| "No key #{key}"} # => "No key nosuch"
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.fetch("z")
+  # Raises KeyError if neither `default_value` nor a block was given.
   #
-  # *produces:*
-  #
-  #     prog.rb:2:in `fetch': key not found (KeyError)
-  #      from prog.rb:2
+  # Note that this method does not use the values of either #default or
+  # #default_proc.
   #
   def fetch: (K arg0) -> V
            | [X] (K arg0, X arg1) -> (V | X)
            | [X] (K arg0) { (K arg0) -> X } -> (V | X)
 
-  # Returns an array containing the values associated with the given keys but also
-  # raises KeyError when one of keys can't be found. Also see Hash#values_at and
-  # Hash#fetch.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.fetch_values(*keys) -> new_array
+  #   - hash.fetch_values(*keys) {|key| ... } -> new_array
+  # -->
+  # Returns a new Array containing the values associated with the given keys
+  # *keys:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.fetch_values(:baz, :foo) # => [2, 0]
+  #
+  # Returns a new empty Array if no arguments given.
   #
-  #     h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" }
+  # When a block is given, calls the block with each missing key, treating the
+  # block's return value as the value for that key:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     values = h.fetch_values(:bar, :foo, :bad, :bam) {|key| key.to_s}
+  #     values # => [1, 0, "bad", "bam"]
   #
-  #     h.fetch_values("cow", "cat")                   #=> ["bovine", "feline"]
-  #     h.fetch_values("cow", "bird")                  # raises KeyError
-  #     h.fetch_values("cow", "bird") { |k| k.upcase } #=> ["bovine", "BIRD"]
+  # When no block is given, raises an exception if any given key is not found.
   #
   def fetch_values: (*K) -> ::Array[V]
                   | [X] (*K) { (K) -> X } -> ::Array[V | X]
 
-  # Returns a new hash consisting of entries for which the block returns true.
-  #
-  # If no block is given, an enumerator is returned instead.
+  # <!-- rdoc-file=hash.c -->
+  # Hash#filter is an alias for Hash#select.
   #
-  #     h = { "a" => 100, "b" => 200, "c" => 300 }
-  #     h.select {|k,v| k > "a"}  #=> {"b" => 200, "c" => 300}
-  #     h.select {|k,v| v < 200}  #=> {"a" => 100}
+  # Returns a new Hash object whose entries are those for which the block returns
+  # a truthy value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.select {|key, value| value < 2 } # => {:foo=>0, :bar=>1}
   #
-  # Hash#filter is an alias for Hash#select.
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.select # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:select>
+  #     e.each {|key, value| value < 2 } # => {:foo=>0, :bar=>1}
   #
   def filter: () { (K, V) -> boolish } -> ::Hash[K, V]
             | () -> ::Enumerator[[ K, V ], ::Hash[K, V]]
 
-  # Equivalent to Hash#keep_if, but returns `nil` if no changes were made.
-  #
+  # <!-- rdoc-file=hash.c -->
   # Hash#filter! is an alias for Hash#select!.
   #
+  # Returns `self`, whose entries are those for which the block returns a truthy
+  # value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.select! {|key, value| value < 2 }  => {:foo=>0, :bar=>1}
+  #
+  # Returns `nil` if no entries were removed.
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.select!  # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:select!>
+  #     e.each { |key, value| value < 2 } # => {:foo=>0, :bar=>1}
+  #
   def filter!: () { (K, V) -> boolish } -> self?
              | () -> ::Enumerator[[ K, V ], self?]
 
-  # Returns a new array that is a one-dimensional flattening of this hash. That
-  # is, for every key or value that is an array, extract its elements into the new
-  # array.  Unlike Array#flatten, this method does not flatten recursively by
-  # default.  The optional *level* argument determines the level of recursion to
-  # flatten.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.flatten -> new_array
+  #   - hash.flatten(level) -> new_array
+  # -->
+  # Returns a new Array object that is a 1-dimensional flattening of `self`.
+  #
+  # ---
+  #
+  # By default, nested Arrays are not flattened:
+  #     h = {foo: 0, bar: [:bat, 3], baz: 2}
+  #     h.flatten # => [:foo, 0, :bar, [:bat, 3], :baz, 2]
+  #
+  # Takes the depth of recursive flattening from Integer argument `level`:
+  #     h = {foo: 0, bar: [:bat, [:baz, [:bat, ]]]}
+  #     h.flatten(1) # => [:foo, 0, :bar, [:bat, [:baz, [:bat]]]]
+  #     h.flatten(2) # => [:foo, 0, :bar, :bat, [:baz, [:bat]]]
+  #     h.flatten(3) # => [:foo, 0, :bar, :bat, :baz, [:bat]]
+  #     h.flatten(4) # => [:foo, 0, :bar, :bat, :baz, :bat]
   #
-  #     a =  {1=> "one", 2 => [2,"two"], 3 => "three"}
-  #     a.flatten    # => [1, "one", 2, [2, "two"], 3, "three"]
-  #     a.flatten(2) # => [1, "one", 2, 2, "two", 3, "three"]
+  # When `level` is negative, flattens all nested Arrays:
+  #     h = {foo: 0, bar: [:bat, [:baz, [:bat, ]]]}
+  #     h.flatten(-1) # => [:foo, 0, :bar, :bat, :baz, :bat]
+  #     h.flatten(-2) # => [:foo, 0, :bar, :bat, :baz, :bat]
+  #
+  # When `level` is zero, returns the equivalent of #to_a :
+  #     h = {foo: 0, bar: [:bat, 3], baz: 2}
+  #     h.flatten(0) # => [[:foo, 0], [:bar, [:bat, 3]], [:baz, 2]]
+  #     h.flatten(0) == h.to_a # => true
   #
   def flatten: () -> ::Array[K | V]
              | (1 level) -> ::Array[K | V]
              | (Integer level) -> Array[untyped]
 
-  # Returns `true` if the given key is present in *hsh*.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.has_key?("a")   #=> true
-  #     h.has_key?("z")   #=> false
+  # <!-- rdoc-file=hash.c -->
+  # Methods #has_key?, #key?, and #member? are aliases for #include?.
   #
-  # Note that #include? and #member? do not test member equality using `==` as do
-  # other Enumerables.
-  #
-  # See also Enumerable#include?
+  # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   def has_key?: (K arg0) -> bool
 
-  # Returns `true` if the given value is present for some key in *hsh*.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.has_value?(value) -> true or false
+  #   - hash.value?(value) -> true or false
+  # -->
+  # Method #value? is an alias for #has_value?.
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.value?(100)   #=> true
-  #     h.value?(999)   #=> false
+  # Returns `true` if `value` is a value in `self`, otherwise `false`.
   #
   def has_value?: (V arg0) -> bool
 
-  # Compute a hash-code for this hash. Two hashes with the same content will have
-  # the same hash code (and will compare using `eql?`).
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.hash -> an_integer
+  # -->
+  # Returns the Integer hash-code for the hash.
   #
-  # See also Object#hash.
+  # Two Hash objects have the same hash-code if their content is the same
+  # (regardless or order):
+  #     h1 = {foo: 0, bar: 1, baz: 2}
+  #     h2 = {baz: 2, bar: 1, foo: 0}
+  #     h2.hash == h1.hash # => true
+  #     h2.eql? h1 # => true
   #
   def hash: () -> Integer
 
-  # Returns `true` if the given key is present in *hsh*.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.has_key?("a")   #=> true
-  #     h.has_key?("z")   #=> false
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.include?(key) -> true or false
+  #   - hash.has_key?(key) -> true or false
+  #   - hash.key?(key) -> true or false
+  #   - hash.member?(key) -> true or false
+  # -->
+  # Methods #has_key?, #key?, and #member? are aliases for #include?.
   #
-  # Note that #include? and #member? do not test member equality using `==` as do
-  # other Enumerables.
-  #
-  # See also Enumerable#include?
+  # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias include? has_key?
 
-  # Return the contents of this hash as a string.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.inspect -> new_string
+  # -->
+  # Returns a new String containing the hash entries:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}"
   #
-  #     h = { "c" => 300, "a" => 100, "d" => 400, "c" => 300  }
-  #     h.to_s   #=> "{\"c\"=>300, \"a\"=>100, \"d\"=>400}"
+  # Hash#to_s is an alias for Hash#inspect.
   #
   def inspect: () -> String
 
-  # Returns a new hash created by using *hsh*'s values as keys, and the keys as
-  # values. If a key with the same value already exists in the *hsh*, then the
-  # last one defined will be used, the earlier value(s) will be discarded.
-  #
-  #     h = { "n" => 100, "m" => 100, "y" => 300, "d" => 200, "a" => 0 }
-  #     h.invert   #=> {0=>"a", 100=>"m", 200=>"d", 300=>"y"}
-  #
-  # If there is no key with the same value, Hash#invert is involutive.
-  #
-  #     h = { a: 1, b: 3, c: 4 }
-  #     h.invert.invert == h #=> true
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.invert -> new_hash
+  # -->
+  # Returns a new Hash object with the each key-value pair inverted:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = h.invert
+  #     h1 # => {0=>:foo, 1=>:bar, 2=>:baz}
   #
-  # The condition, no key with the same value, can be tested by comparing the size
-  # of inverted hash.
-  #
-  #     # no key with the same value
-  #     h = { a: 1, b: 3, c: 4 }
-  #     h.size == h.invert.size #=> true
-  #
-  #     # two (or more) keys has the same value
-  #     h = { a: 1, b: 3, c: 1 }
-  #     h.size == h.invert.size #=> false
+  # Overwrites any repeated new keys: (see [Entry
+  # Order](#class-Hash-label-Entry+Order)):
+  #     h = {foo: 0, bar: 0, baz: 0}
+  #     h.invert # => {0=>:baz}
   #
   def invert: () -> ::Hash[V, K]
 
-  # Deletes every key-value pair from *hsh* for which *block* evaluates to
-  # `false`.
-  #
-  # If no block is given, an enumerator is returned instead.
-  #
-  # See also Hash#select!.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.keep_if {|key, value| ... } -> self
+  #   - hash.keep_if -> new_enumerator
+  # -->
+  # Calls the block for each key-value pair; retains the entry if the block
+  # returns a truthy value; otherwise deletes the entry; returns `self`.
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.keep_if { |key, value| key.start_with?('b') } # => {:bar=>1, :baz=>2}
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.keep_if # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:keep_if>
+  #     e.each { |key, value| key.start_with?('b') } # => {:bar=>1, :baz=>2}
   #
   def keep_if: () { (K, V) -> boolish } -> self
              | () -> ::Enumerator[[ K, V ], self]
 
-  # Returns the key of an occurrence of a given value. If the value is not found,
-  # returns `nil`.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.key(value) -> key or nil
+  # -->
+  # Returns the key for the first-found entry with the given `value` (see [Entry
+  # Order](#class-Hash-label-Entry+Order)):
+  #     h = {foo: 0, bar: 2, baz: 2}
+  #     h.key(0) # => :foo
+  #     h.key(2) # => :bar
   #
-  #     h = { "a" => 100, "b" => 200, "c" => 300, "d" => 300 }
-  #     h.key(200)   #=> "b"
-  #     h.key(300)   #=> "c"
-  #     h.key(999)   #=> nil
+  # Returns `nil` if so such value is found.
   #
   def key: (V) -> K?
 
-  # Returns `true` if the given key is present in *hsh*.
+  # <!-- rdoc-file=hash.c -->
+  # Methods #has_key?, #key?, and #member? are aliases for #include?.
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.has_key?("a")   #=> true
-  #     h.has_key?("z")   #=> false
-  #
-  # Note that #include? and #member? do not test member equality using `==` as do
-  # other Enumerables.
-  #
-  # See also Enumerable#include?
+  # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias key? has_key?
 
-  # Returns a new array populated with the keys from this hash. See also
-  # Hash#values.
-  #
-  #     h = { "a" => 100, "b" => 200, "c" => 300, "d" => 400 }
-  #     h.keys   #=> ["a", "b", "c", "d"]
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.keys -> new_array
+  # -->
+  # Returns a new Array containing all keys in `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.keys # => [:foo, :bar, :baz]
   #
   def keys: () -> ::Array[K]
 
-  # Returns the number of key-value pairs in the hash.
-  #
-  #     h = { "d" => 100, "a" => 200, "v" => 300, "e" => 400 }
-  #     h.size          #=> 4
-  #     h.delete("a")   #=> 200
-  #     h.size          #=> 3
-  #     h.length        #=> 3
+  # <!-- rdoc-file=hash.c -->
+  # Returns the count of entries in `self`:
+  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
   # Hash#length is an alias for Hash#size.
   #
   def length: () -> Integer
 
-  # Returns `true` if the given key is present in *hsh*.
+  # <!-- rdoc-file=hash.c -->
+  # Methods #has_key?, #key?, and #member? are aliases for #include?.
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.has_key?("a")   #=> true
-  #     h.has_key?("z")   #=> false
-  #
-  # Note that #include? and #member? do not test member equality using `==` as do
-  # other Enumerables.
-  #
-  # See also Enumerable#include?
+  # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias member? has_key?
 
-  # Returns a new hash that combines the contents of the receiver and the contents
-  # of the given hashes.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.merge -> copy_of_self
+  #   - hash.merge(*other_hashes) -> new_hash
+  #   - hash.merge(*other_hashes) { |key, old_value, new_value| ... } -> new_hash
+  # -->
+  # 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.
+  #
+  # ---
+  #
+  # With arguments and no block:
+  # *   Returns the new Hash object formed by merging each successive Hash in
+  #     `other_hashes` into `self`.
+  # *   Each new-key entry is added at the end.
+  # *   Each duplicate-key entry's value overwrites the previous value.
+  #
+  #
+  # Example:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = {bat: 3, bar: 4}
+  #     h2 = {bam: 5, bat:6}
+  #     h.merge(h1, h2) # => {:foo=>0, :bar=>4, :baz=>2, :bat=>6, :bam=>5}
+  #
+  # With arguments and a block:
+  # *   Returns a new Hash object that is the merge of `self` and each given hash.
+  # *   The given hashes are merged left to right.
+  # *   Each new-key entry is added at the end.
+  # *   For each duplicate key:
+  #     *   Calls the block with the key and the old and new values.
+  #     *   The block's return value becomes the new value for the entry.
   #
-  # If no block is given, entries with duplicate keys are overwritten with the
-  # values from each `other_hash` successively, otherwise the value for each
-  # duplicate key is determined by calling the block with the key, its value in
-  # the receiver and its value in each `other_hash`.
   #
-  # When called without any argument, returns a copy of the receiver.
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h2 = { "b" => 246, "c" => 300 }
-  #     h3 = { "b" => 357, "d" => 400 }
-  #     h1.merge          #=> {"a"=>100, "b"=>200}
-  #     h1.merge(h2)      #=> {"a"=>100, "b"=>246, "c"=>300}
-  #     h1.merge(h2, h3)  #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
-  #     h1.merge(h2) {|key, oldval, newval| newval - oldval}
-  #                       #=> {"a"=>100, "b"=>46,  "c"=>300}
-  #     h1.merge(h2, h3) {|key, oldval, newval| newval - oldval}
-  #                       #=> {"a"=>100, "b"=>311, "c"=>300, "d"=>400}
-  #     h1                #=> {"a"=>100, "b"=>200}
+  # 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}
+  #
+  # With no arguments:
+  # *   Returns a copy of `self`.
+  # *   The block, if given, is ignored.
+  #
+  #
+  # Example:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.merge # => {:foo=>0, :bar=>1, :baz=>2}
+  #     h1 = h.merge { |key, old_value, new_value| raise 'Cannot happen' }
+  #     h1 # => {:foo=>0, :bar=>1, :baz=>2}
   #
   def merge: [A, B] (*::Hash[A, B] other_hashes) -> ::Hash[A | K, B | V]
-           | [A, B, C] (*::Hash[A, B] other_hashes) { (K key, V oldval, B newval) -> (C) } -> ::Hash[A | K, B | V | C]
+           | [A, B, C] (*::Hash[A, B] other_hashes) { (K key, V oldval, B newval) -> C } -> ::Hash[A | K, B | V | C]
 
-  # Adds the contents of the given hashes to the receiver.
+  # <!-- rdoc-file=hash.c -->
+  # Merges each of `other_hashes` into `self`; returns `self`.
+  #
+  # Each argument in `other_hashes` must be a Hash.
+  #
+  # Method #update is an alias for #merge!.
+  #
+  # With arguments and no block:
+  # *   Returns `self`, after the given hashes are merged into it.
+  # *   The given hashes are merged left to right.
+  # *   Each new entry is added at the end.
+  # *   Each duplicate-key entry's value overwrites the previous value.
+  #
+  #
+  # Example:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = {bat: 3, bar: 4}
+  #     h2 = {bam: 5, bat:6}
+  #     h.merge!(h1, h2) # => {:foo=>0, :bar=>4, :baz=>2, :bat=>6, :bam=>5}
   #
-  # If no block is given, entries with duplicate keys are overwritten with the
-  # values from each `other_hash` successively, otherwise the value for each
-  # duplicate key is determined by calling the block with the key, its value in
-  # the receiver and its value in each `other_hash`.
+  # With arguments and a block:
+  # *   Returns `self`, after the given hashes are merged.
+  # *   The given hashes are merged left to right.
+  # *   Each new-key entry is added at the end.
+  # *   For each duplicate key:
+  #     *   Calls the block with the key and the old and new values.
+  #     *   The block's return value becomes the new value for the entry.
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h1.merge!          #=> {"a"=>100, "b"=>200}
-  #     h1                 #=> {"a"=>100, "b"=>200}
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h2 = { "b" => 246, "c" => 300 }
-  #     h1.merge!(h2)      #=> {"a"=>100, "b"=>246, "c"=>300}
-  #     h1                 #=> {"a"=>100, "b"=>246, "c"=>300}
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h2 = { "b" => 246, "c" => 300 }
-  #     h3 = { "b" => 357, "d" => 400 }
-  #     h1.merge!(h2, h3)
-  #                        #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
-  #     h1                 #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
+  # 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}
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h2 = { "b" => 246, "c" => 300 }
-  #     h3 = { "b" => 357, "d" => 400 }
-  #     h1.merge!(h2, h3) {|key, v1, v2| v1 }
-  #                        #=> {"a"=>100, "b"=>200, "c"=>300, "d"=>400}
-  #     h1                 #=> {"a"=>100, "b"=>200, "c"=>300, "d"=>400}
+  # With no arguments:
+  # *   Returns `self`, unmodified.
+  # *   The block, if given, is ignored.
   #
-  # Hash#update is an alias for Hash#merge!.
+  #
+  # Example:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.merge # => {:foo=>0, :bar=>1, :baz=>2}
+  #     h1 = h.merge! { |key, old_value, new_value| raise 'Cannot happen' }
+  #     h1 # => {:foo=>0, :bar=>1, :baz=>2}
   #
   def merge!: (*::Hash[K, V] other_hashes) -> self
-            | (*::Hash[K, V] other_hashes) { (K key, V oldval, V newval) -> (V) } -> self
+            | (*::Hash[K, V] other_hashes) { (K key, V oldval, V newval) -> V } -> self
 
-  # Searches through the hash comparing *obj* with the value using `==`. Returns
-  # the first key-value pair (two-element array) that matches. See also
-  # Array#rassoc.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.rassoc(value) -> new_array or nil
+  # -->
+  # Returns a new 2-element Array consisting of the key and value of the
+  # first-found entry whose value is `==` to value (see [Entry
+  # Order](#class-Hash-label-Entry+Order)):
+  #     h = {foo: 0, bar: 1, baz: 1}
+  #     h.rassoc(1) # => [:bar, 1]
   #
-  #     a = {1=> "one", 2 => "two", 3 => "three", "ii" => "two"}
-  #     a.rassoc("two")    #=> [2, "two"]
-  #     a.rassoc("four")   #=> nil
+  # Returns `nil` if no such value found.
   #
-  def rassoc: (V) -> [K, V]?
+  def rassoc: (V) -> [ K, V ]?
 
-  # Rebuilds the hash based on the current hash values for each key. If values of
-  # key objects have changed since they were inserted, this method will reindex
-  # *hsh*. If Hash#rehash is called while an iterator is traversing the hash, a
-  # RuntimeError will be raised in the iterator.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.rehash -> self
+  # -->
+  # Rebuilds the hash table by recomputing the hash index for each key; returns
+  # `self`.
   #
-  #     a = [ "a", "b" ]
-  #     c = [ "c", "d" ]
-  #     h = { a => 100, c => 300 }
-  #     h[a]       #=> 100
-  #     a[0] = "z"
-  #     h[a]       #=> nil
-  #     h.rehash   #=> {["z", "b"]=>100, ["c", "d"]=>300}
-  #     h[a]       #=> 100
+  # The hash table becomes invalid if the hash value of a key has changed after
+  # the entry was created. See [Modifying an Active Hash
+  # Key](#class-Hash-label-Modifying+an+Active+Hash+Key).
   #
   def rehash: () -> self
 
-  # Returns a new hash consisting of entries for which the block returns false.
-  #
-  # If no block is given, an enumerator is returned instead.
-  #
-  #     h = { "a" => 100, "b" => 200, "c" => 300 }
-  #     h.reject {|k,v| k < "b"}  #=> {"b" => 200, "c" => 300}
-  #     h.reject {|k,v| v > 100}  #=> {"a" => 100}
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.reject {|key, value| ... } -> new_hash
+  #   - hash.reject -> new_enumerator
+  # -->
+  # Returns a new Hash object whose entries are all those from `self` for which
+  # the block returns `false` or `nil`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = h.reject {|key, value| key.start_with?('b') }
+  #     h1 # => {:foo=>0}
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.reject # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:reject>
+  #     h1 = e.each {|key, value| key.start_with?('b') }
+  #     h1 # => {:foo=>0}
   #
   def reject: () -> ::Enumerator[[ K, V ], self]
             | () { (K, V) -> boolish } -> self
 
-  # Equivalent to Hash#delete_if, but returns `nil` if no changes were made.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.reject! {|key, value| ... } -> self or nil
+  #   - hash.reject! -> new_enumerator
+  # -->
+  # Returns `self`, whose remaining entries are those for which the block returns
+  # `false` or `nil`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.reject! {|key, value| value < 2 } # => {:baz=>2}
+  #
+  # Returns `nil` if no entries are removed.
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.reject! # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:reject!>
+  #     e.each {|key, value| key.start_with?('b') } # => {:foo=>0}
   #
   def reject!: () -> ::Enumerator[[ K, V ], self?]
-            | () { (K, V) -> boolish } -> self?
+             | () { (K, V) -> boolish } -> self?
 
-  # Replaces the contents of *hsh* with the contents of *other_hash*.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.replace({ "c" => 300, "d" => 400 })   #=> {"c"=>300, "d"=>400}
+  # <!-- rdoc-file=hash.c -->
+  # Replaces the entire contents of `self` with the contents of `other_hash`;
+  # returns `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.replace({bat: 3, bam: 4}) # => {:bat=>3, :bam=>4}
   #
   def replace: (Hash[K, V]) -> self
 
-  # Returns a new hash consisting of entries for which the block returns true.
-  #
-  # If no block is given, an enumerator is returned instead.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.select {|key, value| ... } -> new_hash
+  #   - hash.select -> new_enumerator
+  # -->
+  # Hash#filter is an alias for Hash#select.
   #
-  #     h = { "a" => 100, "b" => 200, "c" => 300 }
-  #     h.select {|k,v| k > "a"}  #=> {"b" => 200, "c" => 300}
-  #     h.select {|k,v| v < 200}  #=> {"a" => 100}
+  # Returns a new Hash object whose entries are those for which the block returns
+  # a truthy value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.select {|key, value| value < 2 } # => {:foo=>0, :bar=>1}
   #
-  # Hash#filter is an alias for Hash#select.
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.select # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:select>
+  #     e.each {|key, value| value < 2 } # => {:foo=>0, :bar=>1}
   #
   alias select filter
 
-  # Equivalent to Hash#keep_if, but returns `nil` if no changes were made.
-  #
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.select! {|key, value| ... } -> self or nil
+  #   - hash.select! -> new_enumerator
+  # -->
   # Hash#filter! is an alias for Hash#select!.
   #
+  # Returns `self`, whose entries are those for which the block returns a truthy
+  # value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.select! {|key, value| value < 2 }  => {:foo=>0, :bar=>1}
+  #
+  # Returns `nil` if no entries were removed.
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.select!  # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:select!>
+  #     e.each { |key, value| value < 2 } # => {:foo=>0, :bar=>1}
+  #
   alias select! filter!
 
-  # Removes a key-value pair from *hsh* and returns it as the two-item array `[`
-  # *key, value* `]`, or the hash's default value if the hash is empty.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.shift -> [key, value] or default_value
+  # -->
+  # Removes the first hash entry (see [Entry
+  # Order](#class-Hash-label-Entry+Order)); returns a 2-element Array containing
+  # the removed key and value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.shift # => [:foo, 0]
+  #     h # => {:bar=>1, :baz=>2}
   #
-  #     h = { 1 => "a", 2 => "b", 3 => "c" }
-  #     h.shift   #=> [1, "a"]
-  #     h         #=> {2=>"b", 3=>"c"}
+  # Returns the default value if the hash is empty (see [Default
+  # Values](#class-Hash-label-Default+Values)).
   #
   def shift: () -> [ K, V ]?
 
-  # Returns the number of key-value pairs in the hash.
-  #
-  #     h = { "d" => 100, "a" => 200, "v" => 300, "e" => 400 }
-  #     h.size          #=> 4
-  #     h.delete("a")   #=> 200
-  #     h.size          #=> 3
-  #     h.length        #=> 3
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.length -> integer
+  #   - hash.size -> integer
+  # -->
+  # Returns the count of entries in `self`:
+  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
   # Hash#length is an alias for Hash#size.
   #
   alias size length
 
-  # Returns a hash containing only the given keys and their values.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.slice(*keys) -> new_hash
+  # -->
+  # Returns a new Hash object containing the entries for the given `keys`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.slice(:baz, :foo) # => {:baz=>2, :foo=>0}
   #
-  #     h = { a: 100, b: 200, c: 300 }
-  #     h.slice(:a)           #=> {:a=>100}
-  #     h.slice(:b, :c, :d)   #=> {:b=>200, :c=>300}
+  # Any given `keys` that are not found are ignored.
   #
   def slice: (*K) -> ::Hash[K, V]
 
-  # ## Element Assignment
-  #
-  # Associates the value given by `value` with the key given by `key`.
+  # <!-- rdoc-file=hash.c -->
+  # Hash#store is an alias for Hash#[]=.
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h["a"] = 9
-  #     h["c"] = 4
-  #     h   #=> {"a"=>9, "b"=>200, "c"=>4}
-  #     h.store("d", 42) #=> 42
-  #     h   #=> {"a"=>9, "b"=>200, "c"=>4, "d"=>42}
+  # Associates the given `value` with the given `key`; returns `value`.
   #
-  # `key` should not have its value changed while it is in use as a key (an
-  # `unfrozen String` passed as a key will be duplicated and frozen).
+  # If the given `key` exists, replaces its value with the given `value`; the
+  # ordering is not affected (see [Entry Order](#class-Hash-label-Entry+Order)):
+  #     h = {foo: 0, bar: 1}
+  #     h[:foo] = 2 # => 2
+  #     h.store(:bar, 3) # => 3
+  #     h # => {:foo=>2, :bar=>3}
   #
-  #     a = "a"
-  #     b = "b".freeze
-  #     h = { a => 100, b => 200 }
-  #     h.key(100).equal? a #=> false
-  #     h.key(200).equal? b #=> true
+  # If `key` does not exist, adds the `key` and `value`; the new entry is last in
+  # the order (see [Entry Order](#class-Hash-label-Entry+Order)):
+  #     h = {foo: 0, bar: 1}
+  #     h[:baz] = 2 # => 2
+  #     h.store(:bat, 3) # => 3
+  #     h # => {:foo=>0, :bar=>1, :baz=>2, :bat=>3}
   #
   alias store []=
 
-  # Converts *hsh* to a nested array of `[` *key, value* `]` arrays.
-  #
-  #     h = { "c" => 300, "a" => 100, "d" => 400, "c" => 300  }
-  #     h.to_a   #=> [["c", 300], ["a", 100], ["d", 400]]
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.to_a -> new_array
+  # -->
+  # Returns a new Array of 2-element Array objects; each nested Array contains a
+  # key-value pair from `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.to_a # => [[:foo, 0], [:bar, 1], [:baz, 2]]
   #
   def to_a: () -> ::Array[[ K, V ]]
 
-  # Returns `self`. If called on a subclass of Hash, converts the receiver to a
-  # Hash object.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.to_h -> self or new_hash
+  #   - hash.to_h {|key, value| ... } -> new_hash
+  # -->
+  # For an instance of Hash, returns `self`.
+  #
+  # For a subclass of Hash, returns a new Hash containing the content of `self`.
   #
-  # If a block is given, the results of the block on each pair of the receiver
-  # will be used as pairs.
+  # When a block is given, returns a new Hash object whose content is based on the
+  # block; the block should return a 2-element Array object specifying the
+  # key-value pair to be included in the returned Array:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = h.to_h {|key, value| [value, key] }
+  #     h1 # => {0=>:foo, 1=>:bar, 2=>:baz}
   #
   def to_h: () -> Hash[K, V]
           | [A, B] () { (K, V) -> [ A, B ] } -> Hash[A, B]
 
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.to_hash -> self
+  # -->
   # Returns `self`.
   #
   def to_hash: () -> self
 
-  # Returns a Proc which maps keys to values.
-  #
-  #     h = {a:1, b:2}
-  #     hp = h.to_proc
-  #     hp.call(:a)          #=> 1
-  #     hp.call(:b)          #=> 2
-  #     hp.call(:c)          #=> nil
-  #     [:a, :b, :c].map(&h) #=> [1, 2, nil]
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.to_proc -> proc
+  # -->
+  # Returns a Proc object that maps a key to its value:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     proc = h.to_proc
+  #     proc.class # => Proc
+  #     proc.call(:foo) # => 0
+  #     proc.call(:bar) # => 1
+  #     proc.call(:nosuch) # => nil
   #
   def to_proc: () -> ^(K) -> V?
 
+  # <!-- rdoc-file=hash.c -->
+  # Returns a new String containing the hash entries:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}"
+  #
+  # Hash#to_s is an alias for Hash#inspect.
+  #
   alias to_s inspect
 
-  # Returns a new hash with the results of running the block once for every key.
-  # This method does not change the values.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.transform_keys {|key| ... } -> new_hash
+  #   - hash.transform_keys(hash2) -> new_hash
+  #   - hash.transform_keys(hash2) {|other_key| ...} -> new_hash
+  #   - hash.transform_keys -> new_enumerator
+  # -->
+  # Returns a new Hash object; each entry has:
+  # *   A key provided by the block.
+  # *   The value from `self`.
+  #
+  #
+  # An optional hash argument can be provided to map keys to new keys. Any key not
+  # given will be mapped using the provided block, or remain the same if no block
+  # is given.
+  #
+  # Transform keys:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = h.transform_keys {|key| key.to_s }
+  #     h1 # => {"foo"=>0, "bar"=>1, "baz"=>2}
   #
-  #     h = { a: 1, b: 2, c: 3 }
-  #     h.transform_keys {|k| k.to_s }  #=> { "a" => 1, "b" => 2, "c" => 3 }
-  #     h.transform_keys(&:to_s)        #=> { "a" => 1, "b" => 2, "c" => 3 }
-  #     h.transform_keys.with_index {|k, i| "#{k}.#{i}" }
-  #                                     #=> { "a.0" => 1, "b.1" => 2, "c.2" => 3 }
+  #     h.transform_keys(foo: :bar, bar: :foo)
+  #     #=> {bar: 0, foo: 1, baz: 2}
   #
-  # If no block is given, an enumerator is returned instead.
+  #     h.transform_keys(foo: :hello, &:to_s)
+  #     #=> {:hello=>0, "bar"=>1, "baz"=>2}
+  #
+  # Overwrites values for duplicate keys:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = h.transform_keys {|key| :bat }
+  #     h1 # => {:bat=>2}
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.transform_keys # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:transform_keys>
+  #     h1 = e.each { |key| key.to_s }
+  #     h1 # => {"foo"=>0, "bar"=>1, "baz"=>2}
   #
   def transform_keys: () -> Enumerator[K, Hash[untyped, V]]
                     | [A] () { (K) -> A } -> Hash[A, V]
 
-  # Invokes the given block once for each key in *hsh*, replacing it with the new
-  # key returned by the block, and then returns *hsh*. This method does not change
-  # the values.
-  #
-  #     h = { a: 1, b: 2, c: 3 }
-  #     h.transform_keys! {|k| k.to_s }  #=> { "a" => 1, "b" => 2, "c" => 3 }
-  #     h.transform_keys!(&:to_sym)      #=> { a: 1, b: 2, c: 3 }
-  #     h.transform_keys!.with_index {|k, i| "#{k}.#{i}" }
-  #                                      #=> { "a.0" => 1, "b.1" => 2, "c.2" => 3 }
-  #
-  # If no block is given, an enumerator is returned instead.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.transform_keys! {|key| ... } -> self
+  #   - hash.transform_keys!(hash2) -> self
+  #   - hash.transform_keys!(hash2) {|other_key| ...} -> self
+  #   - hash.transform_keys! -> new_enumerator
+  # -->
+  # Same as Hash#transform_keys but modifies the receiver in place instead of
+  # returning a new hash.
   #
   def transform_keys!: () -> Enumerator[K, self]
                      | () { (K) -> K } -> self
 
-  # Returns a new hash with the results of running the block once for every value.
-  # This method does not change the keys.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.transform_values {|value| ... } -> new_hash
+  #   - hash.transform_values -> new_enumerator
+  # -->
+  # Returns a new Hash object; each entry has:
+  # *   A key from `self`.
+  # *   A value provided by the block.
   #
-  #     h = { a: 1, b: 2, c: 3 }
-  #     h.transform_values {|v| v * v + 1 }  #=> { a: 2, b: 5, c: 10 }
-  #     h.transform_values(&:to_s)           #=> { a: "1", b: "2", c: "3" }
-  #     h.transform_values.with_index {|v, i| "#{v}.#{i}" }
-  #                                          #=> { a: "1.0", b: "2.1", c: "3.2" }
   #
-  # If no block is given, an enumerator is returned instead.
+  # Transform values:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = h.transform_values {|value| value * 100}
+  #     h1 # => {:foo=>0, :bar=>100, :baz=>200}
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.transform_values # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:transform_values>
+  #     h1 = e.each { |value| value * 100}
+  #     h1 # => {:foo=>0, :bar=>100, :baz=>200}
   #
   def transform_values: () -> Enumerator[V, Hash[K, untyped]]
                       | [A] () { (V) -> A } -> Hash[K, A]
 
-  # Invokes the given block once for each value in *hsh*, replacing it with the
-  # new value returned by the block, and then returns *hsh*. This method does not
-  # change the keys.
-  #
-  #     h = { a: 1, b: 2, c: 3 }
-  #     h.transform_values! {|v| v * v + 1 }  #=> { a: 2, b: 5, c: 10 }
-  #     h.transform_values!(&:to_s)           #=> { a: "2", b: "5", c: "10" }
-  #     h.transform_values!.with_index {|v, i| "#{v}.#{i}" }
-  #                                           #=> { a: "2.0", b: "5.1", c: "10.2" }
-  #
-  # If no block is given, an enumerator is returned instead.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.transform_values! {|value| ... } -> self
+  #   - hash.transform_values! -> new_enumerator
+  # -->
+  # Returns `self`, whose keys are unchanged, and whose values are determined by
+  # the given block.
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.transform_values! {|value| value * 100} # => {:foo=>0, :bar=>100, :baz=>200}
+  #
+  # Returns a new Enumerator if no block given:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     e = h.transform_values! # => #<Enumerator: {:foo=>0, :bar=>100, :baz=>200}:transform_values!>
+  #     h1 = e.each {|value| value * 100}
+  #     h1 # => {:foo=>0, :bar=>100, :baz=>200}
   #
   def transform_values!: () -> Enumerator[V, self]
                        | () { (V) -> V } -> self
 
-  # Adds the contents of the given hashes to the receiver.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.merge! -> self
+  #   - hash.merge!(*other_hashes) -> self
+  #   - hash.merge!(*other_hashes) { |key, old_value, new_value| ... } -> self
+  # -->
+  # Merges each of `other_hashes` into `self`; returns `self`.
+  #
+  # Each argument in `other_hashes` must be a Hash.
   #
-  # If no block is given, entries with duplicate keys are overwritten with the
-  # values from each `other_hash` successively, otherwise the value for each
-  # duplicate key is determined by calling the block with the key, its value in
-  # the receiver and its value in each `other_hash`.
+  # Method #update is an alias for #merge!.
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h1.merge!          #=> {"a"=>100, "b"=>200}
-  #     h1                 #=> {"a"=>100, "b"=>200}
+  # With arguments and no block:
+  # *   Returns `self`, after the given hashes are merged into it.
+  # *   The given hashes are merged left to right.
+  # *   Each new entry is added at the end.
+  # *   Each duplicate-key entry's value overwrites the previous value.
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h2 = { "b" => 246, "c" => 300 }
-  #     h1.merge!(h2)      #=> {"a"=>100, "b"=>246, "c"=>300}
-  #     h1                 #=> {"a"=>100, "b"=>246, "c"=>300}
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h2 = { "b" => 246, "c" => 300 }
-  #     h3 = { "b" => 357, "d" => 400 }
-  #     h1.merge!(h2, h3)
-  #                        #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
-  #     h1                 #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
+  # Example:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h1 = {bat: 3, bar: 4}
+  #     h2 = {bam: 5, bat:6}
+  #     h.merge!(h1, h2) # => {:foo=>0, :bar=>4, :baz=>2, :bat=>6, :bam=>5}
   #
-  #     h1 = { "a" => 100, "b" => 200 }
-  #     h2 = { "b" => 246, "c" => 300 }
-  #     h3 = { "b" => 357, "d" => 400 }
-  #     h1.merge!(h2, h3) {|key, v1, v2| v1 }
-  #                        #=> {"a"=>100, "b"=>200, "c"=>300, "d"=>400}
-  #     h1                 #=> {"a"=>100, "b"=>200, "c"=>300, "d"=>400}
+  # With arguments and a block:
+  # *   Returns `self`, after the given hashes are merged.
+  # *   The given hashes are merged left to right.
+  # *   Each new-key entry is added at the end.
+  # *   For each duplicate key:
+  #     *   Calls the block with the key and the old and new values.
+  #     *   The block's return value becomes the new value for the entry.
   #
-  # Hash#update is an alias for Hash#merge!.
+  #
+  #
+  # 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}
+  #
+  # With no arguments:
+  # *   Returns `self`, unmodified.
+  # *   The block, if given, is ignored.
+  #
+  #
+  # Example:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.merge # => {:foo=>0, :bar=>1, :baz=>2}
+  #     h1 = h.merge! { |key, old_value, new_value| raise 'Cannot happen' }
+  #     h1 # => {:foo=>0, :bar=>1, :baz=>2}
   #
   alias update merge!
 
-  # Returns `true` if the given value is present for some key in *hsh*.
+  # <!-- rdoc-file=hash.c -->
+  # Method #value? is an alias for #has_value?.
   #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.value?(100)   #=> true
-  #     h.value?(999)   #=> false
+  # Returns `true` if `value` is a value in `self`, otherwise `false`.
   #
   alias value? has_value?
 
-  # Returns a new array populated with the values from *hsh*. See also Hash#keys.
-  #
-  #     h = { "a" => 100, "b" => 200, "c" => 300 }
-  #     h.values   #=> [100, 200, 300]
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.values -> new_array
+  # -->
+  # Returns a new Array containing all values in `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.values # => [0, 1, 2]
   #
   def values: () -> ::Array[V]
 
-  # Return an array containing the values associated with the given keys. Also see
-  # Hash.select.
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.values_at(*keys) -> new_array
+  # -->
+  # Returns a new Array containing values for the given `keys`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.values_at(:baz, :foo) # => [2, 0]
   #
-  #     h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" }
-  #     h.values_at("cow", "cat")  #=> ["bovine", "feline"]
+  # The [default values](#class-Hash-label-Default+Values) are returned for any
+  # keys that are not found:
+  #     h.values_at(:hello, :foo) # => [nil, 0]
   #
   def values_at: (*K arg0) -> ::Array[V?]
 
   private
 
-  # Returns a new, empty hash. If this hash is subsequently accessed by a key that
-  # doesn't correspond to a hash entry, the value returned depends on the style of
-  # `new` used to create the hash. In the first form, the access returns `nil`. If
-  # *obj* is specified, this single object will be used for all *default values*.
-  # If a block is specified, it will be called with the hash object and the key,
-  # and should return the default value. It is the block's responsibility to store
-  # the value in the hash if required.
-  #
-  #     h = Hash.new("Go Fish")
-  #     h["a"] = 100
-  #     h["b"] = 200
-  #     h["a"]           #=> 100
-  #     h["c"]           #=> "Go Fish"
-  #     # The following alters the single default object
-  #     h["c"].upcase!   #=> "GO FISH"
-  #     h["d"]           #=> "GO FISH"
-  #     h.keys           #=> ["a", "b"]
-  #
-  #     # While this creates a new default object each time
-  #     h = Hash.new { |hash, key| hash[key] = "Go Fish: #{key}" }
-  #     h["c"]           #=> "Go Fish: c"
-  #     h["c"].upcase!   #=> "GO FISH: C"
-  #     h["d"]           #=> "Go Fish: d"
-  #     h.keys           #=> ["c", "d"]
+  # <!--
+  #   rdoc-file=hash.c
+  #   - Hash.new(default_value = nil) -> new_hash
+  #   - Hash.new {|hash, key| ... } -> new_hash
+  # -->
+  # Returns a new empty Hash object.
+  #
+  # The initial default value and initial default proc for the new hash depend on
+  # which form above was used. See [Default
+  # Values](#class-Hash-label-Default+Values).
+  #
+  # If neither an argument nor a block given, initializes both the default value
+  # and the default proc to `nil`:
+  #     h = Hash.new
+  #     h.default # => nil
+  #     h.default_proc # => nil
+  #
+  # If argument `default_value` given but no block given, initializes the default
+  # value to the given `default_value` and the default proc to `nil`:
+  #     h = Hash.new(false)
+  #     h.default # => false
+  #     h.default_proc # => nil
+  #
+  # If a block given but no argument, stores the block as the default proc and
+  # sets the default value to `nil`:
+  #     h = Hash.new {|hash, key| "Default value for #{key}" }
+  #     h.default # => nil
+  #     h.default_proc.class # => Proc
+  #     h[:nosuch] # => "Default value for nosuch"
   #
   def initialize: () -> void
-                             | (untyped default) -> void
-                             | [A, B] () { (Hash[A, B] hash, A key) -> B } -> void
-
-  # Replaces the contents of *hsh* with the contents of *other_hash*.
-  #
-  #     h = { "a" => 100, "b" => 200 }
-  #     h.replace({ "c" => 300, "d" => 400 })   #=> {"c"=>300, "d"=>400}
+                | (untyped default) -> void
+                | [A, B] () { (Hash[A, B] hash, A key) -> B } -> void
+
+  # <!--
+  #   rdoc-file=hash.c
+  #   - hash.replace(other_hash) -> self
+  # -->
+  # Replaces the entire contents of `self` with the contents of `other_hash`;
+  # returns `self`:
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.replace({bat: 3, bam: 4}) # => {:bat=>3, :bam=>4}
   #
   def initialize_copy: (self object) -> self
 end