Merge pull request #2926 from kyanagi/hash-new-capacity

`Hash.new`の`capacity`の説明を追加

Author: znz

refm/api/src/_builtin/Hash

@@ -130,7 +130,12 @@ alist = [[1,["a"]], [2,["b"]], [3,["c"]], [[4,5], ["a", "b"]]]
 hash = Hash[alist] # => {1=>["a"], 2=>["b"], 3=>["c"], [4, 5]=>["a", "b"]}
 #@end
 
+#@until 3.4
 --- new(ifnone = nil) -> Hash
+#@end
+#@since 3.4
+--- new(ifnone = nil, capacity: 0) -> Hash
+#@end
 
 空の新しいハッシュを生成します。ifnone はキーに対
 応する値が存在しない時のデフォルト値です。設定したデフォルト値は[[m:Hash#default]]で参照できます。
@@ -152,7 +157,16 @@ p h.default #=> [0, 1]
 
 #@#デフォルト値の扱いには注意が必要です( [[trap:Hash]] )
 
+#@since 3.4
+capacity を指定すると、指定した要素数を格納するのに充分なメモリをあらかじめ確保します。
+要素数の多いハッシュを構築する際にメモリの再配置やハッシュテーブルの再構築が不要となるため、
+パフォーマンスの改善が期待できます。
+#@end
+
 @param ifnone キーに対応する値が存在しない時のデフォルト値です。
+#@since 3.4
+@param capacity 指定した要素数に相当するメモリをあらかじめ確保します。
+#@end
 
 #@samplecode 例
 h = Hash.new([])
@@ -178,15 +192,24 @@ h[1] << 1
 #@end
 #@end
 
+#@until 3.4
 --- new {|hash, key| ... } -> Hash
+#@end
+#@since 3.4
+--- new(capacity: 0) {|hash, key| ... } -> Hash
+#@end
 空の新しいハッシュを生成します。ブロックの評価結果がデフォルト値になりま
 す。設定したデフォルト値は[[m:Hash#default_proc]]で参照できます。
 
 値が設定されていないハッシュ要素を参照するとその都度ブロックを
 実行し、その結果を返します。
 ブロックにはそのハッシュとハッシュを参照したときのキーが渡されます。
 
-@raise ArgumentError ブロックと通常引数を同時に与えると発生します。
+#@since 3.4
+@param capacity 指定した要素数に相当するメモリをあらかじめ確保します。
+#@end
+
+@raise ArgumentError ifnone などの位置引数とブロックを同時に与えると発生します。
 
 #@samplecode 例
 # ブロックではないデフォルト値は全部同一のオブジェクトなので、