Update RDoc comments with Ruby 4.0.6

.github/workflows/comments.yml

@@ -16,7 +16,7 @@ jobs:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "4.0.1"
+          ruby-version: "4.0.6"
           bundler: none
       - name: Install dependencies
         run: |

Gemfile.lock

@@ -62,7 +62,7 @@ GEM
     diff-lcs (1.6.2)
     digest (3.2.1)
     drb (2.2.3)
-    erb (6.0.4)
+    erb (6.0.6)
     extconf_compile_commands_json (0.0.7)
     ffi (1.17.4)
     fileutils (1.8.0)
@@ -128,9 +128,10 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rdoc (7.2.0)
+    rdoc (8.0.0)
       erb
-      psych (>= 4.0.0)
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
       tsort
     regexp_parser (2.12.0)
     reline (0.6.3)

core/pathname.rbs

@@ -234,11 +234,6 @@ class Pathname
   #
   def +: (Pathname | String | _ToStr other) -> Pathname
 
-  # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - /(other)
-  # -->
-  #
   alias / +
 
   # <!--
@@ -271,11 +266,6 @@ class Pathname
   #
   def ==: (untyped) -> bool
 
-  # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - ===(other)
-  # -->
-  #
   def ===: (untyped) -> bool
 
   # <!--

core/ractor.rbs

@@ -470,11 +470,6 @@ class Ractor
   #
   def self.store_if_absent: [A] (Symbol) { (nil) -> A } -> A
 
-  # <!--
-  #   rdoc-file=ractor.rb
-  #   - <<(...)
-  # -->
-  #
   alias << send
 
   # <!--
@@ -746,11 +741,6 @@ class Ractor
   # Port objects transmit messages between Ractors.
   #
   class Port[T = untyped]
-    # <!--
-    #   rdoc-file=ractor.rb
-    #   - <<(obj, move: false)
-    # -->
-    #
     alias << send
 
     # <!--

core/rubygems/errors.rbs

@@ -17,7 +17,7 @@
 # Further RubyGems documentation can be found at:
 #
 # *   [RubyGems Guides](https://guides.rubygems.org)
-# *   [RubyGems API](https://www.rubydoc.info/github/ruby/rubygems) (also
+# *   [RubyGems API](https://guides.rubygems.org/rubygems-org-api/) (also
 #     available from `gem server`)
 #
 # ## RubyGems Plugins
@@ -90,6 +90,9 @@
 #
 # -The RubyGems Team
 #
+# <!-- rdoc-file=lib/rubygems/version.rb -->
+# Workaround for directly loading Gem::Version in some cases
+#
 module Gem
   # <!-- rdoc-file=lib/rubygems/errors.rb -->
   # Raised when RubyGems is unable to load or activate a gem.  Contains the name

core/rubygems/requirement.rbs

@@ -123,18 +123,8 @@ module Gem
     #
     def satisfied_by?: (Gem::Version version) -> bool
 
-    # <!--
-    #   rdoc-file=lib/rubygems/requirement.rb
-    #   - ===(version)
-    # -->
-    #
     alias === satisfied_by?
 
-    # <!--
-    #   rdoc-file=lib/rubygems/requirement.rb
-    #   - =~(version)
-    # -->
-    #
     alias =~ satisfied_by?
 
     # <!--

core/rubygems/rubygems.rbs

@@ -17,7 +17,7 @@
 # Further RubyGems documentation can be found at:
 #
 # *   [RubyGems Guides](https://guides.rubygems.org)
-# *   [RubyGems API](https://www.rubydoc.info/github/ruby/rubygems) (also
+# *   [RubyGems API](https://guides.rubygems.org/rubygems-org-api/) (also
 #     available from `gem server`)
 #
 # ## RubyGems Plugins
@@ -90,6 +90,9 @@
 #
 # -The RubyGems Team
 #
+# <!-- rdoc-file=lib/rubygems/version.rb -->
+# Workaround for directly loading Gem::Version in some cases
+#
 module Gem
   interface _HashLike[K, V]
     def each_pair: () { ([ K, V ]) -> untyped } -> self

core/rubygems/specification.rbs

@@ -19,5 +19,13 @@
 # #metadata for restrictions on the format and size of metadata items you may
 # add to a specification.
 #
+# Specifications must be deterministic, as in the example above. For instance,
+# you cannot define attributes conditionally:
+#
+#     # INVALID: do not do this.
+#     unless RUBY_ENGINE == "jruby"
+#       s.extensions << "ext/example/extconf.rb"
+#     end
+#
 class Gem::Specification < Gem::BasicSpecification
 end

core/rubygems/version.rbs

@@ -1,165 +1,5 @@
 %a{annotate:rdoc:skip}
 module Gem
-  # <!-- rdoc-file=lib/rubygems/version.rb -->
-  # The Version class processes string versions into comparable values. A version
-  # string should normally be a series of numbers separated by periods. Each part
-  # (digits separated by periods) is considered its own number, and these are used
-  # for sorting. So for instance, 3.10 sorts higher than 3.2 because ten is
-  # greater than two.
-  #
-  # If any part contains letters (currently only a-z are supported) then that
-  # version is considered prerelease. Versions with a prerelease part in the Nth
-  # part sort less than versions with N-1 parts. Prerelease parts are sorted
-  # alphabetically using the normal Ruby string sorting rules. If a prerelease
-  # part contains both letters and numbers, it will be broken into multiple parts
-  # to provide expected sort behavior (1.0.a10 becomes 1.0.a.10, and is greater
-  # than 1.0.a9).
-  #
-  # Prereleases sort between real releases (newest to oldest):
-  #
-  # 1.  1.0
-  # 2.  1.0.b1
-  # 3.  1.0.a.2
-  # 4.  0.9
-  #
-  # If you want to specify a version restriction that includes both prereleases
-  # and regular releases of the 1.x series this is the best way:
-  #
-  #     s.add_dependency 'example', '>= 1.0.0.a', '< 2.0.0'
-  #
-  # ## How Software Changes
-  #
-  # Users expect to be able to specify a version constraint that gives them some
-  # reasonable expectation that new versions of a library will work with their
-  # software if the version constraint is true, and not work with their software
-  # if the version constraint is false.  In other words, the perfect system will
-  # accept all compatible versions of the library and reject all incompatible
-  # versions.
-  #
-  # Libraries change in 3 ways (well, more than 3, but stay focused here!).
-  #
-  # 1.  The change may be an implementation detail only and have no effect on the
-  #     client software.
-  # 2.  The change may add new features, but do so in a way that client software
-  #     written to an earlier version is still compatible.
-  # 3.  The change may change the public interface of the library in such a way
-  #     that old software is no longer compatible.
-  #
-  # Some examples are appropriate at this point.  Suppose I have a Stack class
-  # that supports a `push` and a `pop` method.
-  #
-  # ### Examples of Category 1 changes:
-  #
-  # *   Switch from an array based implementation to a linked-list based
-  #     implementation.
-  # *   Provide an automatic (and transparent) backing store for large stacks.
-  #
-  # ### Examples of Category 2 changes might be:
-  #
-  # *   Add a `depth` method to return the current depth of the stack.
-  # *   Add a `top` method that returns the current top of stack (without changing
-  #     the stack).
-  # *   Change `push` so that it returns the item pushed (previously it had no
-  #     usable return value).
-  #
-  # ### Examples of Category 3 changes might be:
-  #
-  # *   Changes `pop` so that it no longer returns a value (you must use `top` to
-  #     get the top of the stack).
-  # *   Rename the methods to `push_item` and `pop_item`.
-  #
-  # ## RubyGems Rational Versioning
-  #
-  # *   Versions shall be represented by three non-negative integers, separated by
-  #     periods (e.g. 3.1.4).  The first integers is the "major" version number,
-  #     the second integer is the "minor" version number, and the third integer is
-  #     the "build" number.
-  #
-  # *   A category 1 change (implementation detail) will increment the build
-  #     number.
-  #
-  # *   A category 2 change (backwards compatible) will increment the minor
-  #     version number and reset the build number.
-  #
-  # *   A category 3 change (incompatible) will increment the major build number
-  #     and reset the minor and build numbers.
-  #
-  # *   Any "public" release of a gem should have a different version.  Normally
-  #     that means incrementing the build number.  This means a developer can
-  #     generate builds all day long, but as soon as they make a public release,
-  #     the version must be updated.
-  #
-  # ### Examples
-  #
-  # Let's work through a project lifecycle using our Stack example from above.
-  #
-  # Version 0.0.1
-  # :   The initial Stack class is release.
-  #
-  # Version 0.0.2
-  # :   Switched to a linked=list implementation because it is cooler.
-  #
-  # Version 0.1.0
-  # :   Added a `depth` method.
-  #
-  # Version 1.0.0
-  # :   Added `top` and made `pop` return nil (`pop` used to return the  old top
-  #     item).
-  #
-  # Version 1.1.0
-  # :   `push` now returns the value pushed (it used it return nil).
-  #
-  # Version 1.1.1
-  # :   Fixed a bug in the linked list implementation.
-  #
-  # Version 1.1.2
-  # :   Fixed a bug introduced in the last fix.
-  #
-  #
-  # Client A needs a stack with basic push/pop capability.  They write to the
-  # original interface (no `top`), so their version constraint looks like:
-  #
-  #     gem 'stack', '>= 0.0'
-  #
-  # Essentially, any version is OK with Client A.  An incompatible change to the
-  # library will cause them grief, but they are willing to take the chance (we
-  # call Client A optimistic).
-  #
-  # Client B is just like Client A except for two things: (1) They use the `depth`
-  # method and (2) they are worried about future incompatibilities, so they write
-  # their version constraint like this:
-  #
-  #     gem 'stack', '~> 0.1'
-  #
-  # The `depth` method was introduced in version 0.1.0, so that version or
-  # anything later is fine, as long as the version stays below version 1.0 where
-  # incompatibilities are introduced.  We call Client B pessimistic because they
-  # are worried about incompatible future changes (it is OK to be pessimistic!).
-  #
-  # ## Preventing Version Catastrophe:
-  #
-  # From:
-  # https://www.zenspider.com/ruby/2008/10/rubygems-how-to-preventing-catastrophe.
-  # html
-  #
-  # Let's say you're depending on the fnord gem version 2.y.z. If you specify your
-  # dependency as ">= 2.0.0" then, you're good, right? What happens if fnord 3.0
-  # comes out and it isn't backwards compatible with 2.y.z? Your stuff will break
-  # as a result of using ">=". The better route is to specify your dependency with
-  # an "approximate" version specifier ("~>"). They're a tad confusing, so here is
-  # how the dependency specifiers work:
-  #
-  #     Specification From  ... To (exclusive)
-  #     ">= 3.0"      3.0   ... &infin;
-  #     "~> 3.0"      3.0   ... 4.0
-  #     "~> 3.0.0"    3.0.0 ... 3.1
-  #     "~> 3.5"      3.5   ... 4.0
-  #     "~> 3.5.0"    3.5.0 ... 3.6
-  #     "~> 3"        3.0   ... 4.0
-  #
-  # For the last example, single-digit versions are automatically extended with a
-  # zero to give a sensible result.
-  #
   class Version
     include Comparable
 

core/thread.rbs

@@ -1565,10 +1565,10 @@ class Thread::Mutex < Object
 
   # <!--
   #   rdoc-file=thread_sync.rb
-  #   - mutex.lock  -> self
+  #   - mutex.unlock  -> self
   # -->
-  # Attempts to grab the lock and waits if it isn't available. Raises
-  # `ThreadError` if `mutex` was locked by the current thread.
+  # Releases the lock. Raises `ThreadError` if `mutex` wasn't locked by the
+  # current thread.
   #
   def unlock: () -> self
 end
@@ -1751,11 +1751,6 @@ end
 # See Thread::Queue for an example of how a Thread::SizedQueue works.
 #
 class Thread::SizedQueue[E = untyped] < Thread::Queue[E]
-  # <!--
-  #   rdoc-file=thread_sync.rb
-  #   - <<(object, non_block = false, timeout: nil)
-  # -->
-  #
   alias << push
 
   # <!--

stdlib/delegate/0/delegator.rbs

@@ -94,7 +94,7 @@ class Delegator < BasicObject
   #   rdoc-file=lib/delegate.rb
   #   - freeze()
   # -->
-  # :method: freeze Freeze both the object returned by `__getobj__` and self.
+  # Freeze both the object returned by `__getobj__` and self.
   #
   def freeze: () -> self
 
@@ -118,6 +118,7 @@ class Delegator < BasicObject
   #   rdoc-file=lib/delegate.rb
   #   - method_missing(m, *args, &block)
   # -->
+  # Handles the magic of delegation through `__getobj__`.
   #
   def method_missing: (Symbol m, *untyped args, **untyped) { (*untyped, **untyped) -> untyped } -> untyped
 

stdlib/digest/0/digest.rbs

@@ -536,13 +536,19 @@ class Digest::SHA2 < Digest::Class
   #
   def update: (String) -> self
 
-  private def finish: () -> String
-
   # <!--
-  #   rdoc-file=ext/digest/sha2/lib/sha2.rb
-  #   - <<(str)
+  #   rdoc-file=ext/digest/digest.c
+  #   - digest_obj.instance_eval { finish } -> digest_obj
   # -->
+  # Finishes the digest and returns the resulting hash value.
   #
+  # This method is overridden by each implementation subclass and often made
+  # private, because some of those subclasses may leave internal data
+  # uninitialized.  Do not call this method from outside.  Use #digest!() instead,
+  # which ensures that internal data be reset for security reasons.
+  #
+  private def finish: () -> String
+
   alias << update
 
   # <!--

stdlib/erb/0/erb.rbs

@@ -633,7 +633,7 @@ class ERB
   # # => "The time is 2025-09-18 15:58:08 -0500."
   #
   # In a more readable format:
-  #     # puts erb.src.split('; ')
+  #       # puts erb.src.split('; ')
   #   # #coding:UTF-8
   #   # _erbout = +''
   #   # _erbout.<< "The time is ".freeze