Merge pull request #1889 from ruby/ruby-3-3-3

Update docs for ruby-3.3.3

core/rubygems/errors.rbs

@@ -94,6 +94,72 @@
 #
 # -The RubyGems Team
 #
+# <!-- rdoc-file=lib/rubygems/deprecate.rb -->
+# Provides 3 methods for declaring when something is going away.
+#
+# +deprecate(name, repl, year, month)+:
+#     Indicate something may be removed on/after a certain date.
+#
+# +rubygems_deprecate(name, replacement=:none)+:
+#     Indicate something will be removed in the next major RubyGems version,
+#     and (optionally) a replacement for it.
+#
+# `rubygems_deprecate_command`:
+#     Indicate a RubyGems command (in +lib/rubygems/commands/*.rb+) will be
+#     removed in the next RubyGems version.
+#
+# Also provides `skip_during` for temporarily turning off deprecation warnings.
+# This is intended to be used in the test suite, so deprecation warnings don't
+# cause test failures if you need to make sure stderr is otherwise empty.
+#
+# Example usage of `deprecate` and `rubygems_deprecate`:
+#
+#     class Legacy
+#       def self.some_class_method
+#         # ...
+#       end
+#
+#       def some_instance_method
+#         # ...
+#       end
+#
+#       def some_old_method
+#         # ...
+#       end
+#
+#       extend Gem::Deprecate
+#       deprecate :some_instance_method, "X.z", 2011, 4
+#       rubygems_deprecate :some_old_method, "Modern#some_new_method"
+#
+#       class << self
+#         extend Gem::Deprecate
+#         deprecate :some_class_method, :none, 2011, 4
+#       end
+#     end
+#
+# Example usage of `rubygems_deprecate_command`:
+#
+#     class Gem::Commands::QueryCommand < Gem::Command
+#       extend Gem::Deprecate
+#       rubygems_deprecate_command
+#
+#       # ...
+#     end
+#
+# Example usage of `skip_during`:
+#
+#     class TestSomething < Gem::Testcase
+#       def test_some_thing_with_deprecations
+#         Gem::Deprecate.skip_during do
+#           actual_stdout, actual_stderr = capture_output do
+#             Gem.something_deprecated
+#           end
+#           assert_empty actual_stdout
+#           assert_equal(expected, actual_stderr)
+#         end
+#       end
+#     end
+#
 module Gem
   # <!-- rdoc-file=lib/rubygems/errors.rb -->
   # Raised when RubyGems is unable to load or activate a gem.  Contains the name

core/rubygems/rubygems.rbs

@@ -94,6 +94,72 @@
 #
 # -The RubyGems Team
 #
+# <!-- rdoc-file=lib/rubygems/deprecate.rb -->
+# Provides 3 methods for declaring when something is going away.
+#
+# +deprecate(name, repl, year, month)+:
+#     Indicate something may be removed on/after a certain date.
+#
+# +rubygems_deprecate(name, replacement=:none)+:
+#     Indicate something will be removed in the next major RubyGems version,
+#     and (optionally) a replacement for it.
+#
+# `rubygems_deprecate_command`:
+#     Indicate a RubyGems command (in +lib/rubygems/commands/*.rb+) will be
+#     removed in the next RubyGems version.
+#
+# Also provides `skip_during` for temporarily turning off deprecation warnings.
+# This is intended to be used in the test suite, so deprecation warnings don't
+# cause test failures if you need to make sure stderr is otherwise empty.
+#
+# Example usage of `deprecate` and `rubygems_deprecate`:
+#
+#     class Legacy
+#       def self.some_class_method
+#         # ...
+#       end
+#
+#       def some_instance_method
+#         # ...
+#       end
+#
+#       def some_old_method
+#         # ...
+#       end
+#
+#       extend Gem::Deprecate
+#       deprecate :some_instance_method, "X.z", 2011, 4
+#       rubygems_deprecate :some_old_method, "Modern#some_new_method"
+#
+#       class << self
+#         extend Gem::Deprecate
+#         deprecate :some_class_method, :none, 2011, 4
+#       end
+#     end
+#
+# Example usage of `rubygems_deprecate_command`:
+#
+#     class Gem::Commands::QueryCommand < Gem::Command
+#       extend Gem::Deprecate
+#       rubygems_deprecate_command
+#
+#       # ...
+#     end
+#
+# Example usage of `skip_during`:
+#
+#     class TestSomething < Gem::Testcase
+#       def test_some_thing_with_deprecations
+#         Gem::Deprecate.skip_during do
+#           actual_stdout, actual_stderr = capture_output do
+#             Gem.something_deprecated
+#           end
+#           assert_empty actual_stdout
+#           assert_equal(expected, actual_stderr)
+#         end
+#       end
+#     end
+#
 module Gem
   interface _HashLike[K, V]
     def each_pair: () { ([ K, V ]) -> untyped } -> self

stdlib/strscan/0/string_scanner.rbs

@@ -184,10 +184,10 @@ class StringScanner
   # If nothing was priorly matched, it returns nil.
   #
   #     s = StringScanner.new("Fri Dec 12 1975 14:39")
-  #     s.scan(/(\w+) (\w+) (\d+) /)       # -> "Fri Dec 12 "
-  #     s.captures                         # -> ["Fri", "Dec", "12"]
-  #     s.scan(/(\w+) (\w+) (\d+) /)       # -> nil
-  #     s.captures                         # -> nil
+  #     s.scan(/(\w+) (\w+) (\d+) (1980)?/)       # -> "Fri Dec 12 "
+  #     s.captures                                # -> ["Fri", "Dec", "12", nil]
+  #     s.scan(/(\w+) (\w+) (\d+) (1980)?/)       # -> nil
+  #     s.captures                                # -> nil
   #
   def captures: () -> Array[String]?