rbs 2.8.4 → 3.8.1

data/core/hash.rbs

@@ -1,19 +1,18 @@
 # <!-- rdoc-file=hash.c -->
-# A Hash maps each of its unique keys to a specific value.
+# A `Hash` maps each of its unique keys to a specific value.
 #
-# A Hash has certain similarities to an Array, but:
+# 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` key can be (almost) any object.
 #
+# ### `Hash` Data Syntax
 #
-# ### Hash Data Syntax
-#
-# The older syntax for Hash data uses the "hash rocket," `=>`:
+# The older syntax for `Hash` data uses the "hash rocket," `=>`:
 #
 #     h = {:foo => 0, :bar => 1, :baz => 2}
 #     h # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# Alternatively, but only for a Hash key that's a Symbol, you can use a newer
+# 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:
 #
 #     h = {foo: 0, bar: 1, baz: 2}
@@ -35,8 +34,8 @@
 #     # Raises SyntaxError (syntax error, unexpected ':', expecting =>):
 #     h = {0: 'zero'}
 #
-# Hash value can be omitted, meaning that value will be fetched from the context
-# by the name of the key:
+# `Hash` value can be omitted, meaning that value will be fetched from the
+# context by the name of the key:
 #
 #     x = 0
 #     y = 100
@@ -45,24 +44,24 @@
 #
 # ### Common Uses
 #
-# You can use a Hash to give names to objects:
+# You can use a `Hash` to give names to objects:
 #
 #     person = {name: 'Matz', language: 'Ruby'}
 #     person # => {:name=>"Matz", :language=>"Ruby"}
 #
-# You can use a Hash to give names to method arguments:
+# You can use a `Hash` to give names to method arguments:
 #
 #     def some_method(hash)
 #       p hash
 #     end
 #     some_method({foo: 0, bar: 1, baz: 2}) # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# Note: when the last argument in a method call is a Hash, the curly braces may
-# be omitted:
+# Note: when the last argument in a method call is a `Hash`, the curly braces
+# may be omitted:
 #
 #     some_method(foo: 0, bar: 1, baz: 2) # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# You can use a Hash to initialize an object:
+# You can use a `Hash` to initialize an object:
 #
 #     class Dev
 #       attr_accessor :name, :language
@@ -74,58 +73,56 @@
 #     matz = Dev.new(name: 'Matz', language: 'Ruby')
 #     matz # => #<Dev: @name="Matz", @language="Ruby">
 #
-# ### Creating a Hash
-#
-# You can create a Hash object explicitly with:
+# ### Creating a `Hash`
 #
-# *   A [hash literal](doc/syntax/literals_rdoc.html#label-Hash+Literals).
+# You can create a `Hash` object explicitly with:
 #
+# *   A [hash literal](rdoc-ref:syntax/literals.rdoc@Hash+Literals).
 #
 # You can convert certain objects to Hashes with:
 #
-# *   Method [Hash](Kernel.html#method-i-Hash).
-#
+# *   Method #Hash.
 #
-# You can create a Hash by calling method Hash.new.
+# You can create a `Hash` by calling method Hash.new.
 #
-# Create an empty Hash:
+# Create an empty `Hash`:
 #
 #     h = Hash.new
 #     h # => {}
 #     h.class # => Hash
 #
-# You can create a Hash by calling method Hash.[].
+# You can create a `Hash` by calling method Hash.[].
 #
-# Create an empty Hash:
+# Create an empty `Hash`:
 #
 #     h = Hash[]
 #     h # => {}
 #
-# Create a Hash with initial entries:
+# 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).
+# You can create a `Hash` by using its literal form (curly braces).
 #
-# Create an empty Hash:
+# Create an empty `Hash`:
 #
 #     h = {}
 #     h # => {}
 #
-# Create a Hash with initial entries:
+# Create a `Hash` with initial entries:
 #
 #     h = {foo: 0, bar: 1, baz: 2}
 #     h # => {:foo=>0, :bar=>1, :baz=>2}
 #
-# ### Hash Value Basics
+# ### `Hash` Value Basics
 #
-# The simplest way to retrieve a Hash value (instance method #[]):
+# 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 #[]=):
+# The simplest way to create or update a `Hash` value (instance method #[]=):
 #
 #     h = {foo: 0, bar: 1, baz: 2}
 #     h[:bat] = 3 # => 3
@@ -133,7 +130,7 @@
 #     h[:foo] = 4 # => 4
 #     h # => {:foo=>4, :bar=>1, :baz=>2, :bat=>3}
 #
-# The simplest way to delete a Hash entry (instance method #delete):
+# The simplest way to delete a `Hash` entry (instance method #delete):
 #
 #     h = {foo: 0, bar: 1, baz: 2}
 #     h.delete(:bar) # => 1
@@ -141,15 +138,14 @@
 #
 # ### Entry Order
 #
-# A Hash object presents its entries in the order of their creation. This is
+# 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:
+# A new `Hash` has its initial ordering per the given entries:
 #
 #     h = Hash[foo: 0, bar: 1]
 #     h # => {:foo=>0, :bar=>1}
@@ -170,18 +166,18 @@
 #     h[:foo] = 5
 #     h # => {:bar=>1, :baz=>3, :foo=>5}
 #
-# ### Hash Keys
+# ### `Hash` Keys
 #
-# #### Hash Key Equivalence
+# #### `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 an Active `Hash` Key
 #
-# Modifying a Hash key while it is in use damages the hash's index.
+# Modifying a `Hash` key while it is in use damages the hash's index.
 #
-# This Hash has keys that are Arrays:
+# This `Hash` has keys that are Arrays:
 #
 #     a0 = [ :foo, :bar ]
 #     a1 = [ :baz, :bat ]
@@ -195,7 +191,7 @@
 #     a0[0] = :bam
 #     a0.hash # => 1069447059
 #
-# And damages the Hash index:
+# And damages the `Hash` index:
 #
 #     h.include?(a0) # => false
 #     h[a0] # => nil
@@ -215,10 +211,10 @@
 #     first_key = h.keys.first
 #     first_key.frozen? # => true
 #
-# #### User-Defined Hash Keys
+# #### 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
+# To be usable 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?`.
 #
@@ -247,7 +243,7 @@
 #       alias eql? ==
 #
 #       def hash
-#         @author.hash ^ @title.hash # XOR
+#         [self.class, @author, @title].hash
 #       end
 #     end
 #
@@ -307,7 +303,7 @@
 #
 # #### Default Proc
 #
-# When the default proc for a Hash is set (i.e., not `nil`), the default value
+# 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:
@@ -324,8 +320,8 @@
 #     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:
+# 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"
@@ -345,219 +341,160 @@
 # Note that setting the default proc will clear the default value and vice
 # versa.
 #
+# Be aware that a default proc that modifies the hash is not thread-safe in the
+# sense that multiple threads can call into the default proc concurrently for
+# the same key.
+#
 # ### What's Here
 #
-# First, what's elsewhere. Class Hash:
+# 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
+# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Enumerable](rdoc-ref:Enumerable@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)
+# Here, class `Hash` provides methods that are useful for:
+#
+# *   [Creating a Hash](rdoc-ref:Hash@Methods+for+Creating+a+Hash)
+# *   [Setting Hash State](rdoc-ref:Hash@Methods+for+Setting+Hash+State)
+# *   [Querying](rdoc-ref:Hash@Methods+for+Querying)
+# *   [Comparing](rdoc-ref:Hash@Methods+for+Comparing)
+# *   [Fetching](rdoc-ref:Hash@Methods+for+Fetching)
+# *   [Assigning](rdoc-ref:Hash@Methods+for+Assigning)
+# *   [Deleting](rdoc-ref:Hash@Methods+for+Deleting)
+# *   [Iterating](rdoc-ref:Hash@Methods+for+Iterating)
+# *   [Converting](rdoc-ref:Hash@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.
+#     Values](rdoc-ref:Hash@Methods+for+Transforming+Keys+and+Values)
+# *   [And more....](rdoc-ref:Hash@Other+Methods)
 #
-# #### Methods for Creating a Hash
+# Class `Hash` also includes methods from module Enumerable.
 #
-# ::[]
-# :   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 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 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`.
-#
+# *   #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? (aliased as #value?): Returns whether a given object is a
+#     value in `self`.
+# *   #include? (aliased as #has_key?, #member?, #key?): Returns whether a given
+#     object is a key in `self`.
+# *   #size (aliased as #length): Returns the count of entries.
 #
 # #### 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.
-#
+# *   #<: Returns whether `self` is a proper subset of a given object.
+# *   #<=: Returns whether `self` is a subset of a given object.
+# *   #==: Returns whether a given object is equal to `self`.
+# *   #>: Returns whether `self` is a proper superset of a given object
+# *   #>=: Returns whether `self` is a 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
+# *   #[]: 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.
-#
+# *   #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.
-#
+# *   #[]= (aliased as #store): Associates a given key with a given value.
+# *   #merge: Returns the hash formed by merging each given hash into a copy of
+#     `self`.
+# *   #update (aliased as #merge!): Merges each given hash into `self`.
+# *   #replace (aliased as #initialize_copy): Replaces the entire contents of
+#     `self` with the contents of a given 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.
-#
+# *   #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.
+# *   #select! (aliased as #filter!): 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.
-#
+# *   #compact: Returns a copy of `self` with all `nil`-valued entries removed.
+# *   #except: Returns a copy of `self` with entries removed for specified keys.
+# *   #select (aliased as #filter): 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.
-#
+# *   #each_pair (aliased as #each): 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.
-#
+# *   #inspect (aliased as #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`.
-#
+# *   #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.
+# *   #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 ]]
 
+  interface _Key
+    def hash: () -> Integer
+
+    def eql?: (untyped rhs) -> boolish
+  end
+
   # <!--
   #   rdoc-file=hash.c
   #   - Hash[] -> new_empty_hash
@@ -565,23 +502,23 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - Hash[ [*2_element_arrays] ] -> new_hash
   #   - Hash[*objects] -> new_hash
   # -->
-  # Returns a new Hash object populated with the given objects, if any. See
+  # Returns a new `Hash` object populated with the given objects, if any. See
   # Hash::new.
   #
-  # With no argument, returns a new empty Hash.
+  # 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.
+  # 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` object wherein each 2-element array forms a key-value entry:
   #
   #     Hash[ [ [:foo, 0], [:bar, 1] ] ] # => {:foo=>0, :bar=>1}
   #
-  # When the argument count is an even number; returns a new Hash object wherein
+  # 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:
   #
   #     Hash[:foo, 0, :bar, 1] # => {:foo=>0, :bar=>1}
@@ -596,20 +533,18 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   rdoc-file=hash.c
   #   - Hash.try_convert(obj) -> obj, new_hash, or nil
   # -->
-  # If `obj` is a Hash object, returns `obj`.
+  # If `obj` is a `Hash` object, returns `obj`.
   #
   # 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.
+  # 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
-
   # <!--
   #   rdoc-file=hash.c
   #   - hash < other_hash -> true or false
@@ -642,11 +577,10 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash == object -> true or false
   # -->
   # Returns `true` if all of the following are true:
-  # *   `object` is a Hash object.
+  # *   `object` is a `Hash` object.
   # *   `hash` and `object` have the same keys (regardless of order).
   # *   For each key `key`, `hash[key] == object[key]`.
   #
-  #
   # Otherwise, returns `false`.
   #
   # Equal:
@@ -694,30 +628,28 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     h[:foo] # => 0
   #
   # If `key` is not found, returns a default value (see [Default
-  # Values](#class-Hash-label-Default+Values)):
+  # Values](rdoc-ref:Hash@Default+Values)):
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h[:nosuch] # => nil
   #
-  def []: (K arg0) -> V
+  def []: %a{implicitly-returns-nil} (K arg0) -> V
 
   # <!--
   #   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)):
+  # ordering is not affected (see [Entry Order](rdoc-ref:Hash@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)):
+  # the order (see [Entry Order](rdoc-ref:Hash@Entry+Order)):
   #     h = {foo: 0, bar: 1}
   #     h[:baz] = 2 # => 2
   #     h.store(:bat, 3) # => 3
@@ -733,6 +665,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   # -->
   # Returns `true` if any element satisfies a given criterion; `false` otherwise.
   #
+  # If `self` has no element, returns `false` and argument or block are not used.
+  #
   # With no argument and no block, returns `true` if `self` is non-empty; `false`
   # if empty.
   #
@@ -749,6 +683,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     h.any? {|key, value| value < 3 } # => true
   #     h.any? {|key, value| value > 3 } # => false
   #
+  # Related: Enumerable#any?
+  #
   def any?: () -> bool
           | (untyped pattern) -> bool
           | () { (K, V) -> boolish } -> bool
@@ -847,7 +783,7 @@ class Hash[unchecked out K, unchecked out V] < 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).
+  # Values](rdoc-ref:Hash@Default+Values).
   #
   # With no argument, returns the current default value:
   #     h = {}
@@ -871,7 +807,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     h.default = false # => false
   #     h.default # => false
   #
-  # See [Default Values](#class-Hash-label-Default+Values).
+  # See [Default Values](rdoc-ref:Hash@Default+Values).
   #
   def default=: (V arg0) -> V
 
@@ -880,7 +816,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.default_proc -> proc or nil
   # -->
   # Returns the default proc for `self` (see [Default
-  # Values](#class-Hash-label-Default+Values)):
+  # Values](rdoc-ref:Hash@Default+Values)):
   #     h = {}
   #     h.default_proc # => nil
   #     h.default_proc = proc {|hash, key| "Default value for #{key}" }
@@ -892,8 +828,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   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)):
+  # Sets the default proc for `self` to `proc` (see [Default
+  # Values](rdoc-ref:Hash@Default+Values)):
   #     h = {}
   #     h.default_proc # => nil
   #     h.default_proc = proc { |hash, key| "Default value for #{key}" }
@@ -970,8 +906,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     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:
+  # This method will use the [default values](rdoc-ref:Hash@Default+Values) for
+  # keys that are not present:
   #     h = {foo: {bar: [:a, :b, :c]}}
   #     h.dig(:hello) # => nil
   #     h.default_proc = -> (hash, _key) { hash }
@@ -981,8 +917,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   def dig: (K, *untyped) -> untyped
 
   # <!-- rdoc-file=hash.c -->
-  # 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}
@@ -1041,8 +975,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - 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}
@@ -1105,17 +1037,15 @@ class Hash[unchecked out K, unchecked out V] < Object
 
   # <!--
   #   rdoc-file=hash.c
-  #   - hash.eql? object -> true or false
+  #   - hash.eql?(object) -> true or false
   # -->
   # Returns `true` if all of the following are true:
-  # *   `object` is a Hash object.
+  # *   `object` is a `Hash` object.
   # *   `hash` and `object` have the same keys (regardless of order).
-  # *   For each key `key`, `h[key] eql? object[key]`.
-  #
+  # *   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
@@ -1128,7 +1058,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   rdoc-file=hash.c
   #   - hsh.except(*keys) -> a_hash
   # -->
-  # Returns a new Hash excluding entries for the given `keys`:
+  # Returns a new `Hash` excluding entries for the given `keys`:
   #     h = { a: 100, b: 200, c: 300 }
   #     h.except(:a)          #=> {:b=>200, :c=>300}
   #
@@ -1186,10 +1116,8 @@ class Hash[unchecked out K, unchecked out V] < Object
                   | [X] (*K) { (K) -> X } -> ::Array[V | X]
 
   # <!-- rdoc-file=hash.c -->
-  # Hash#filter is an alias for Hash#select.
-  #
-  # Returns a new Hash object whose entries are those for which the block returns
-  # a truthy value:
+  # 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}
   #
@@ -1202,8 +1130,6 @@ class Hash[unchecked out K, unchecked out V] < Object
             | () -> ::Enumerator[[ K, V ], ::Hash[K, V]]
 
   # <!-- 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}
@@ -1254,8 +1180,6 @@ class Hash[unchecked out K, unchecked out V] < Object
              | (Integer level) -> Array[untyped]
 
   # <!-- rdoc-file=hash.c -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   def has_key?: (K arg0) -> bool
@@ -1265,8 +1189,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.has_value?(value) -> true or false
   #   - hash.value?(value) -> true or false
   # -->
-  # Method #value? is an alias for #has_value?.
-  #
   # Returns `true` if `value` is a value in `self`, otherwise `false`.
   #
   def has_value?: (V arg0) -> bool
@@ -1277,8 +1199,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   # -->
   # Returns the Integer hash-code for the hash.
   #
-  # Two Hash objects have the same hash-code if their content is the same
-  # (regardless or order):
+  # Two `Hash` objects have the same hash-code if their content is the same
+  # (regardless of order):
   #     h1 = {foo: 0, bar: 1, baz: 2}
   #     h2 = {baz: 2, bar: 1, foo: 0}
   #     h2.hash == h1.hash # => true
@@ -1293,8 +1215,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.key?(key) -> true or false
   #   - hash.member?(key) -> true or false
   # -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias include? has_key?
@@ -1304,10 +1224,9 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - 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}"
   #
-  # Hash#to_s is an alias for Hash#inspect.
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.inspect # => "{foo: 0, bar: 1, baz: 2}"
   #
   def inspect: () -> String
 
@@ -1315,13 +1234,13 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   rdoc-file=hash.c
   #   - hash.invert -> new_hash
   # -->
-  # Returns a new Hash object with the each key-value pair inverted:
+  # 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}
   #
   # Overwrites any repeated new keys: (see [Entry
-  # Order](#class-Hash-label-Entry+Order)):
+  # Order](rdoc-ref:Hash@Entry+Order)):
   #     h = {foo: 0, bar: 0, baz: 0}
   #     h.invert # => {0=>:baz}
   #
@@ -1350,18 +1269,16 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - 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)):
+  # Order](rdoc-ref:Hash@Entry+Order)):
   #     h = {foo: 0, bar: 2, baz: 2}
   #     h.key(0) # => :foo
   #     h.key(2) # => :bar
   #
-  # Returns `nil` if so such value is found.
+  # Returns `nil` if no such value is found.
   #
   def key: (V) -> K?
 
   # <!-- rdoc-file=hash.c -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias key? has_key?
@@ -1378,15 +1295,12 @@ class Hash[unchecked out K, unchecked out V] < Object
 
   # <!-- 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.
+  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
   def length: () -> Integer
 
   # <!-- rdoc-file=hash.c -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias member? has_key?
@@ -1397,20 +1311,19 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - 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
+  # 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.
+  # 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
+  # *   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}
@@ -1418,15 +1331,14 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     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.
+  # *   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.
   #
-  #
-  #
   # Example:
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h1 = {bat: 3, bar: 4}
@@ -1438,7 +1350,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   # *   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}
@@ -1451,9 +1362,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   # <!-- 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!.
+  # Each argument in `other_hashes` must be a `Hash`.
   #
   # With arguments and no block:
   # *   Returns `self`, after the given hashes are merged into it.
@@ -1461,7 +1370,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   # *   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}
@@ -1476,8 +1384,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     *   Calls the block with the key and the old and new values.
   #     *   The block's return value becomes the new value for the entry.
   #
-  #
-  #
   # Example:
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h1 = {bat: 3, bar: 4}
@@ -1489,7 +1395,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   # *   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}
@@ -1505,7 +1410,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   # -->
   # 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)):
+  # Order](rdoc-ref:Hash@Entry+Order)):
   #     h = {foo: 0, bar: 1, baz: 1}
   #     h.rassoc(1) # => [:bar, 1]
   #
@@ -1522,7 +1427,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   #
   # 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).
+  # Key](rdoc-ref:Hash@Modifying+an+Active+Hash+Key).
   #
   def rehash: () -> self
 
@@ -1531,7 +1436,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.reject {|key, value| ... } -> new_hash
   #   - hash.reject -> new_enumerator
   # -->
-  # Returns a new Hash object whose entries are all those from `self` for which
+  # 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') }
@@ -1579,10 +1484,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.select {|key, value| ... } -> new_hash
   #   - hash.select -> new_enumerator
   # -->
-  # Hash#filter is an alias for Hash#select.
-  #
-  # Returns a new Hash object whose entries are those for which the block returns
-  # a truthy value:
+  # 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}
   #
@@ -1598,8 +1501,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - 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}
@@ -1616,17 +1517,15 @@ class Hash[unchecked out K, unchecked out V] < Object
 
   # <!--
   #   rdoc-file=hash.c
-  #   - hash.shift -> [key, value] or default_value
+  #   - hash.shift -> [key, value] or nil
   # -->
-  # Removes the first hash entry (see [Entry
-  # Order](#class-Hash-label-Entry+Order)); returns a 2-element Array containing
-  # the removed key and value:
+  # Removes the first hash entry (see [Entry Order](rdoc-ref:Hash@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}
   #
-  # Returns the default value if the hash is empty (see [Default
-  # Values](#class-Hash-label-Default+Values)).
+  # Returns nil if the hash is empty.
   #
   def shift: () -> [ K, V ]?
 
@@ -1636,9 +1535,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - 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.
+  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
   alias size length
 
@@ -1646,7 +1544,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   rdoc-file=hash.c
   #   - hash.slice(*keys) -> new_hash
   # -->
-  # Returns a new Hash object containing the entries for the given `keys`:
+  # 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}
   #
@@ -1655,19 +1553,17 @@ class Hash[unchecked out K, unchecked out V] < Object
   def slice: (*K) -> ::Hash[K, V]
 
   # <!-- rdoc-file=hash.c -->
-  # 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)):
+  # ordering is not affected (see [Entry Order](rdoc-ref:Hash@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)):
+  # the order (see [Entry Order](rdoc-ref:Hash@Entry+Order)):
   #     h = {foo: 0, bar: 1}
   #     h[:baz] = 2 # => 2
   #     h.store(:bat, 3) # => 3
@@ -1691,12 +1587,13 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.to_h -> self or new_hash
   #   - hash.to_h {|key, value| ... } -> new_hash
   # -->
-  # For an instance of Hash, returns `self`.
+  # For an instance of `Hash`, returns `self`.
   #
-  # For a subclass of Hash, returns a new Hash containing the content of `self`.
+  # For a subclass of `Hash`, returns a new `Hash` containing the content of
+  # `self`.
   #
-  # 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
+  # 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] }
@@ -1729,10 +1626,9 @@ class Hash[unchecked out K, unchecked out V] < Object
 
   # <!-- 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.
+  #     h = {foo: 0, bar: 1, baz: 2}
+  #     h.inspect # => "{foo: 0, bar: 1, baz: 2}"
   #
   alias to_s inspect
 
@@ -1743,11 +1639,10 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.transform_keys(hash2) {|other_key| ...} -> new_hash
   #   - hash.transform_keys -> new_enumerator
   # -->
-  # Returns a new Hash object; each entry has:
+  # 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.
@@ -1795,11 +1690,10 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.transform_values {|value| ... } -> new_hash
   #   - hash.transform_values -> new_enumerator
   # -->
-  # Returns a new Hash object; each entry has:
+  # Returns a new `Hash` object; each entry has:
   # *   A key from `self`.
   # *   A value provided by the block.
   #
-  #
   # Transform values:
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h1 = h.transform_values {|value| value * 100}
@@ -1841,9 +1735,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   # -->
   # 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!.
+  # Each argument in `other_hashes` must be a `Hash`.
   #
   # With arguments and no block:
   # *   Returns `self`, after the given hashes are merged into it.
@@ -1851,7 +1743,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   # *   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}
@@ -1866,8 +1757,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     *   Calls the block with the key and the old and new values.
   #     *   The block's return value becomes the new value for the entry.
   #
-  #
-  #
   # Example:
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h1 = {bat: 3, bar: 4}
@@ -1879,7 +1768,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   # *   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}
@@ -1889,8 +1777,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   alias update merge!
 
   # <!-- rdoc-file=hash.c -->
-  # Method #value? is an alias for #has_value?.
-  #
   # Returns `true` if `value` is a value in `self`, otherwise `false`.
   #
   alias value? has_value?
@@ -1913,8 +1799,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h.values_at(:baz, :foo) # => [2, 0]
   #
-  # The [default values](#class-Hash-label-Default+Values) are returned for any
-  # keys that are not found:
+  # The [default values](rdoc-ref:Hash@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?]
@@ -1922,38 +1808,45 @@ class Hash[unchecked out K, unchecked out V] < Object
   private
 
   # <!--
-  #   rdoc-file=hash.c
+  #   rdoc-file=hash.rb
   #   - Hash.new(default_value = nil) -> new_hash
+  #   - Hash.new(default_value = nil, capacity: size) -> new_hash
   #   - Hash.new {|hash, key| ... } -> new_hash
+  #   - Hash.new(capacity: size) {|hash, key| ... } -> new_hash
   # -->
-  # Returns a new empty Hash object.
+  # 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).
+  # which form above was used. See [Default Values](rdoc-ref:Hash@Default+Values).
   #
-  # If neither an argument nor a block given, initializes both the default value
-  # and the default proc to `nil`:
+  # If neither an argument nor a block is 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`:
+  # If argument `default_value` is given but no block is 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`:
+  # If a block is given but no `default_value`, 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
+  # If both a block and a `default_value` are given, raises an `ArgumentError`
+  #
+  # If the optional keyword argument `capacity` is given, the hash will be
+  # allocated with enough capacity to accommodate this many keys without having to
+  # be resized.
+  #
+  def initialize: (?capacity: int) -> void
+                | [V] (V default, ?capacity: int) -> void
+                | [A, B] (?capacity: int) { (Hash[A, B] hash, A key) -> B } -> void
 
   # <!--
   #   rdoc-file=hash.c