Improve docs on initial/default values passed to Array.new and Hash.new (#13962)

Co-authored-by: Quinton Miller <[email protected]>

Author: straight-shoota

src/array.cr

@@ -127,12 +127,21 @@ class Array(T)
   #
   # ```
   # Array.new(3, 'a') # => ['a', 'a', 'a']
+  # ```
+  #
+  # WARNING: The initial value is filled into the array as-is. It gets neither
+  # duplicated nor cloned. For types with reference semantics this means every
+  # item will point to the *same* object.
   #
+  # ```
   # ary = Array.new(3, [1])
   # ary # => [[1], [1], [1]]
   # ary[0][0] = 2
   # ary # => [[2], [2], [2]]
   # ```
+  #
+  # * `.new(Int, & : Int32 -> T)` is an alternative that allows using a
+  #   different initial value for each position.
   def initialize(size : Int, value : T)
     if size < 0
       raise ArgumentError.new("Negative array size: #{size}")

src/hash.cr

@@ -266,6 +266,16 @@ class Hash(K, V)
   # Creates a new empty `Hash` with a *block* that handles missing keys.
   #
   # ```
+  # inventory = Hash(String, Int32).new(0)
+  # inventory["socks"] = 3
+  # inventory["pickles"] # => 0
+  # ```
+  #
+  # WARNING: When the default block is invoked on a missing key, its return
+  # value is *not* implicitly stored into the hash under that key. If you want
+  # that behaviour, you need to put it explicitly:
+  #
+  # ```
   # hash = Hash(String, Int32).new do |hash, key|
   #   hash[key] = key.size
   # end
@@ -294,14 +304,23 @@ class Hash(K, V)
   # inventory["pickles"] # => 0
   # ```
   #
-  # NOTE: The default value is passed by reference:
+  # WARNING: When the default value gets returned on a missing key, it is *not*
+  # stored into the hash under that key. If you want that behaviour, please use
+  # the overload with a block.
+  #
+  # WARNING: The default value is returned as-is. It gets neither duplicated nor
+  # cloned. For types with reference semantics this means it will be exactly the
+  # *same* object every time.
+  #
   # ```
-  # arr = [1, 2, 3]
-  # hash = Hash(String, Array(Int32)).new(arr)
-  # hash["3"][1] = 4
-  # arr # => [1, 4, 3]
+  # hash = Hash(String, Array(Int32)).new([1])
+  # hash["a"][0] = 2
+  # hash["b"] # => [2]
   # ```
   #
+  # * `.new(&block : (Hash(K, V), K -> V))` is an alternative with a block that
+  #   can return a different default value for each invocation.
+  #
   # The *initial_capacity* is useful to avoid unnecessary reallocations
   # of the internal buffer in case of growth. If the number of elements
   # a hash will hold is known, the hash should be initialized with that