Merge pull request #2520 from ima1zumi/update-warning-warn-and-kernel…

…-warn

Update Warning.warn and Kernel.warn since 3.0.0

refm/api/src/_builtin/Warning

@@ -38,7 +38,11 @@ category の警告を表示するかどうかのフラグを設定します。
 @see [[m:Warning.[] ]]
 #@end
 
+#@since 3.0.0
+--- warn(message, category: nil) -> nil
+#@else
 --- warn(message) -> nil
+#@end
 
 引数 message を標準エラー出力 [[m:$stderr]] に出力します。
 
@@ -47,6 +51,17 @@ category の警告を表示するかどうかのフラグを設定します。
 またオーバーライドしたメソッドからは super を呼び出すことで、デフォルトの動作である [[m:$stderr]] への出力ができます。
 
 #@samplecode
+#@since 3.0.0
+module Warning
+  # 警告メッセージに category を表示し、message 末尾に !!! を追加する
+  def self.warn(message, category: nil)
+    super("#{category} warning : #{message.chomp}!!!\n")
+  end
+end
+
+warn("hoge", category: :deprecated)
+# => deprecated warning : hoge!!!
+#@else
 warn "hoge" # => hoge
 
 module Warning
@@ -58,21 +73,30 @@ end
 
 warn "hoge" # => hoge!!!
 #@end
+#@end
 
 @param message 出力するオブジェクトを指定します。
 
+@param category 警告のカテゴリを指定します。サポートされている category については [[m:Warning.[] ]] を参照してください。
+
 @see [[m:Kernel.#warn]], [[m:Warning#warn]]
 
 == Public Instance Methods
 
+#@since 3.0.0
+--- warn(message, category: nil) -> nil
+#@else
 --- warn(message) -> nil
+#@end
 
 引数 message を標準エラー出力 [[m:$stderr]] に出力します。
 
 [[m:Kernel.#warn]]の挙動を変更する際は、このメソッドではなくクラスメソッドである[[m:Warning.warn]]をオーバーライドする必要があります。
 
 @param message 出力するオブジェクトを指定します。
 
+@param category 警告のカテゴリを指定します。サポートされている category については [[m:Warning.[] ]] を参照してください。
+
 #@# TODO: messageに改行を渡さないとそのまま出力されるように見えるため、確認してから記載する。
 #@# Writes warning message msg to $stderr, followed by a newline if the message does not end in a newline.
 

refm/api/src/_builtin/functions

@@ -1574,11 +1574,15 @@ to_s メソッドにより文字列に変換してから出力します。
 
 @see [[m:Kernel.#print]], [[m:Kernel.#p]], [[m:IO#puts]]
 
+#@since 3.0.0
+--- warn(*message, uplevel: nil, category: nil) -> nil
+#@else
 #@since 2.5.0
 --- warn(*message, uplevel: nil) -> nil
 #@else
 --- warn(*message) -> nil
 #@end
+#@end
 
 message を 標準エラー出力 [[m:$stderr]] に出力します。 [[m:$VERBOSE]]
 フラグ が nil のときは何も出力しません。
@@ -1600,6 +1604,9 @@ nil
 #@since 2.5.0
 @param uplevel いくつ前の呼び出し元のファイル名と行番号を表示するかを0以上の数値で指定します。 nil の場合は表示しません。
 #@end
+#@since 3.0.0
+@param category 警告のカテゴリを指定します。サポートされている category については [[m:Warning.[] ]] を参照してください。
+#@end
 @raise IOError 標準エラー出力が書き込み用にオープンされていなければ発生します。
 @raise Errno::EXXX 出力に失敗した場合に発生します。
 
@@ -1620,6 +1627,18 @@ foo
 #@end
 #@end
 
+#@since 3.0.0
+#@samplecode category の例
+Warning[:deprecated] = true # 非推奨の警告を表示する
+warn("deprecated!!", category: :deprecated)
+# => deprecated!
+
+Warning[:deprecated] = false # 非推奨の警告を表示しない
+warn("deprecated!!", category: :deprecated)
+# 警告は出力されない
+#@end
+#@end
+
 #@since 2.4.0
 @see [[m:Warning#warn]], [[m:$stderr]],[[m:$VERBOSE]]
 #@else