Use category: :deprecated in warnings that are related to deprecation

Also document that both :deprecated and :experimental are supported
:category option values.

The locations where warnings were marked as deprecation warnings
was previously reviewed by shyouhei.

Comment a couple locations where deprecation warnings should probably
be used but are not currently used because deprecation warning
enablement has not occurred at the time they are called
(RUBY_FREE_MIN, RUBY_HEAP_MIN_SLOTS, -K).

Add assert_deprecated_warn to test assertions.  Use this to simplify
some tests, and fix failing tests after marking some warnings with
deprecated category.

1 files changed, 8 insertions, 3 deletions

diff --git a/warning.rb b/warning.rb
index 764e352296..0012ffb1d6 100644
--- a/warning.rb
+++ b/warning.rb
@@ -39,9 +39,14 @@ module Kernel
   #
   #    baz.rb:6: warning: invalid call to foo
   #
-  # If the +category+ keyword argument is given, it is passed to
-  # Warning.warn method.
-  #
+  # If <code>category</code> keyword argument is given, passes the category
+  # to <code>Warning.warn</code>.  The category given must be be one of the
+  # following categories:
+  #
+  # :deprecated :: Used for warning for deprecated functionality that may
+  #                be removed in the future.
+  # :experimental :: Used for experimental features that may change in
+  #                  future releases.
   def warn(*msgs, uplevel: nil, category: nil)
     Primitive.rb_warn_m(msgs, uplevel, category)
   end