[DOC] Tweaks for Hash.new

1 files changed, 7 insertions, 3 deletions

diff --git a/hash.rb b/hash.rb
index cc42252f12..99b34a9bda 100644
--- a/hash.rb
+++ b/hash.rb
@@ -4,8 +4,10 @@ class Hash
   #   Hash.new(capacity: 0) {|self, key| ... } -> new_hash
   #
   # Returns a new empty \Hash object.
+  #
   # Initializes the values of Hash#default and Hash#default_proc,
-  # which determine the value to be returned by method Hash#[] when the entry does not exist.
+  # which determine the behavior when a given key is not found;
+  # see {Key Not Found?}[rdoc-ref:Hash@Key+Not+Found-3F].
   #
   # By default, a hash has +nil+ values for both +default+ and +default_proc+:
   #
@@ -13,19 +15,21 @@ class Hash
   #   h.default           # => nil
   #   h.default_proc      # => nil
   #
-  # If the +default_value+ argument is provided, it sets the +default+ value for the hash:
+  # With argument +default_value+ given, sets the +default+ value for the hash:
   #
   #   h = Hash.new(false) # => {}
   #   h.default           # => false
   #   h.default_proc      # => nil
   #
-  # If a block is given, it sets the +default_proc+ value:
+  # With a block given, sets the +default_proc+ value:
   #
   #   h = Hash.new {|hash, key| "Hash #{hash}: Default value for #{key}" }
   #   h.default      # => nil
   #   h.default_proc # => #<Proc:0x00000289b6fa7048 (irb):185>
   #   h[:nosuch]     # => "Hash {}: Default value for nosuch"
   #
+  # Raises ArgumentError if both +default_value+ and a block are given.
+  #
   # If optional keyword argument +capacity+ is given with a positive integer value +n+,
   # initializes the hash with enough capacity to accommodate +n+ entries without resizing.
   #