rbs 3.10.0 → 4.0.0.dev.1

data/core/range.rbs

@@ -86,14 +86,14 @@
 #     end
 #     a # => [2, 4, 6, 8, 10]
 #
-# A range can be both beginless and endless. For literal beginless, endless
+# A range can be both beginless and endless.  For literal beginless, endless
 # ranges, at least the beginning or end of the range must be given as an
 # explicit nil value. It is recommended to use an explicit nil beginning and
-# end, since that is what Ruby uses for Range#inspect:
+# implicit nil end, since that is what Ruby uses for Range#inspect:
 #
-#     (nil..)    # => (nil..nil)
-#     (..nil)    # => (nil..nil)
-#     (nil..nil) # => (nil..nil)
+#     (nil..)    # => (nil..)
+#     (..nil)    # => (nil..)
+#     (nil..nil) # => (nil..)
 #
 # ## Ranges and Other Classes
 #
@@ -351,7 +351,7 @@ class Range[out Elem] < Object
   # -->
   # Returns an element from `self` selected by a binary search.
   #
-  # See [Binary Searching](rdoc-ref:language/bsearch.rdoc).
+  # See [Binary Searching](rdoc-ref:bsearch.rdoc).
   #
   def bsearch: () -> ::Enumerator[Elem, Elem?]
              | () { (Elem) -> (true | false) } -> Elem?
@@ -936,7 +936,8 @@ class Range[out Elem] < Object
   #
   # Related: Range#count.
   #
-  def size: () -> (Integer | Float | nil)
+  def size: () -> Integer?
+          | () -> Float?
 
   # <!--
   #   rdoc-file=range.c

data/core/rational.rbs

@@ -53,16 +53,15 @@ class Rational < Numeric
 
   # <!--
   #   rdoc-file=rational.c
-  #   - self * other -> numeric
+  #   - rat * numeric  ->  numeric
   # -->
-  # Returns the numeric product of `self` and `other`:
+  # Performs multiplication.
   #
-  #     Rational(9, 8)  * 4               #=> (9/2)
-  #     Rational(20, 9) * 9.8             #=> 21.77777777777778
-  #     Rational(9, 8)  * Complex(1, 2)   # => ((9/8)+(9/4)*i)
-  #     Rational(2, 3)  * Rational(2, 3)  #=> (4/9)
-  #     Rational(900)   * Rational(1)     #=> (900/1)
-  #     Rational(-2, 9) * Rational(-9, 2) #=> (1/1)
+  #     Rational(2, 3)  * Rational(2, 3)   #=> (4/9)
+  #     Rational(900)   * Rational(1)      #=> (900/1)
+  #     Rational(-2, 9) * Rational(-9, 2)  #=> (1/1)
+  #     Rational(9, 8)  * 4                #=> (9/2)
+  #     Rational(20, 9) * 9.8              #=> 21.77777777777778
   #
   def *: (Integer) -> Rational
        | (Rational) -> Rational
@@ -70,9 +69,9 @@ class Rational < Numeric
 
   # <!--
   #   rdoc-file=rational.c
-  #   - self ** exponent -> numeric
+  #   - rat ** numeric  ->  numeric
   # -->
-  # Returns `self` raised to the power `exponent`:
+  # Performs exponentiation.
   #
   #     Rational(2)    ** Rational(3)     #=> (8/1)
   #     Rational(10)   ** -2              #=> (1/100)
@@ -86,25 +85,15 @@ class Rational < Numeric
 
   # <!--
   #   rdoc-file=rational.c
-  #   - self + other -> numeric
+  #   - rat + numeric  ->  numeric
   # -->
-  # Returns the sum of `self` and `other`:
+  # Performs addition.
   #
-  #     Rational(2, 3) + 0  # => (2/3)
-  #     Rational(2, 3) + 1  # => (5/3)
-  #     Rational(2, 3) + -1 # => (-1/3)
-  #
-  #     Rational(2, 3) + Complex(1, 0)     # => ((5/3)+0i)
-  #
-  #     Rational(2, 3) + Rational(1, 1)     # => (5/3)
-  #     Rational(2, 3) + Rational(3, 2)     # => (13/6)
-  #     Rational(2, 3) + Rational(3.0, 2.0) # => (13/6)
-  #     Rational(2, 3) + Rational(3.1, 2.1) # => (30399297484750849/14186338826217063)
-  #
-  # For a computation involving Floats, the result may be inexact (see Float#+):
-  #
-  #     Rational(2, 3) + 1.0 # => 1.6666666666666665
-  #     Rational(2, 3) + Complex(1.0, 0.0) # => (1.6666666666666665+0.0i)
+  #     Rational(2, 3)  + Rational(2, 3)   #=> (4/3)
+  #     Rational(900)   + Rational(1)      #=> (901/1)
+  #     Rational(-2, 9) + Rational(-9, 2)  #=> (-85/18)
+  #     Rational(9, 8)  + 4                #=> (41/8)
+  #     Rational(20, 9) + 9.8              #=> 12.022222222222222
   #
   def +: (Float) -> Float
        | (Complex) -> Complex
@@ -114,9 +103,9 @@ class Rational < Numeric
 
   # <!--
   #   rdoc-file=rational.c
-  #   - self - other -> numeric
+  #   - rat - numeric  ->  numeric
   # -->
-  # Returns the difference of `self` and `other`:
+  # Performs subtraction.
   #
   #     Rational(2, 3)  - Rational(2, 3)   #=> (0/1)
   #     Rational(900)   - Rational(1)      #=> (899/1)
@@ -130,20 +119,18 @@ class Rational < Numeric
 
   # <!--
   #   rdoc-file=rational.c
-  #   - -self -> rational
+  #   - -rat  ->  rational
   # -->
-  # Returns `self`, negated:
-  #
-  #     -(1/3r)   # => (-1/3)
-  #     -(-1/3r)  # => (1/3)
+  # Negates `rat`.
   #
   def -@: () -> Rational
 
   # <!--
   #   rdoc-file=rational.c
-  #   - self / other -> numeric
+  #   - rat / numeric     ->  numeric
+  #   - rat.quo(numeric)  ->  numeric
   # -->
-  # Returns the quotient of `self` and `other`:
+  # Performs division.
   #
   #     Rational(2, 3)  / Rational(2, 3)   #=> (1/1)
   #     Rational(900)   / Rational(1)      #=> (900/1)
@@ -377,7 +364,7 @@ class Rational < Numeric
   def positive?: () -> bool
 
   # <!-- rdoc-file=rational.c -->
-  # Returns the quotient of `self` and `other`:
+  # Performs division.
   #
   #     Rational(2, 3)  / Rational(2, 3)   #=> (1/1)
   #     Rational(900)   / Rational(1)      #=> (900/1)

data/core/rbs/unnamed/argf.rbs

@@ -93,7 +93,7 @@ module RBS
     # *   File `t.rb`:
     #
     #         p "ARGV: #{ARGV}"
-    #         p "Read: #{ARGF.read}" # Read everything from all specified streams.
+    #         p "Line: #{ARGF.read}" # Read everything from all specified streams.
     #
     # *   Command and output:
     #
@@ -836,7 +836,7 @@ module RBS
       # Formats and writes `objects` to the stream.
       #
       # For details on `format_string`, see [Format
-      # Specifications](rdoc-ref:language/format_specifications.rdoc).
+      # Specifications](rdoc-ref:format_specifications.rdoc).
       #
       %a{annotate:rdoc:copy:ARGF#printf}
       def printf: (String format_string, *untyped args) -> nil

data/core/rbs/unnamed/env_class.rbs

@@ -140,7 +140,7 @@ module RBS
     #
     # *   ::assoc: Returns a 2-element array containing the name and value of the
     #     named environment variable if it exists:
-    # *   ::clone: Raises an exception.
+    # *   ::clone: Returns `ENV` (and issues a warning).
     # *   ::except: Returns a hash of all name/value pairs except those given.
     # *   ::fetch: Returns the value for the given name.
     # *   ::inspect: Returns the contents of `ENV` as a string.

data/core/rbs/unnamed/random.rbs

@@ -31,11 +31,9 @@ module RBS
       #     prng.rand(100)       # => 42
       #
       # When `max` is a Float, `rand` returns a random floating point number between
-      # 0.0 and `max`, including 0.0 and excluding `max`. Note that it behaves
-      # differently from Kernel.rand.
+      # 0.0 and `max`, including 0.0 and excluding `max`.
       #
-      #     prng.rand(1.5)  # => 1.4600282860034115
-      #     rand(1.5)       # => 0
+      #     prng.rand(1.5)       # => 1.4600282860034115
       #
       # When `range` is a Range, `rand` returns a random number where
       # `range.member?(number) == true`.

data/core/regexp.rbs

@@ -39,7 +39,7 @@
 #     most such methods accept an argument that may be either a string or the
 #     (much more powerful) regexp.
 #
-#     See [Regexp Methods](rdoc-ref:language/regexp/methods.rdoc).
+#     See [Regexp Methods](rdoc-ref:regexp/methods.rdoc).
 #
 # ## Regexp Objects
 #
@@ -126,9 +126,6 @@
 #     `nil`. Note that `$0` is quite different; it returns the name of the
 #     currently executing program.
 #
-# These variables, except for `$~`, are shorthands for methods of `$~`.  See
-# MatchData@Global+variables+equivalence.
-#
 # Examples:
 #
 #     # Matched string, but no matched groups.
@@ -438,9 +435,6 @@
 #     /(?<=<b>)\w+(?=<\/b>)/.match("Fortune favors the <b>bold</b>.")
 #     # => #<MatchData "bold">
 #
-# The pattern in lookbehind must be fixed-width. But top-level alternatives can
-# be of various lengths. ex. (?<=a|bc) is OK. (?<=aaa(?:b|cd)) is not allowed.
-#
 # #### Match-Reset Anchor
 #
 # *   `\K`: Match reset: the matched content preceding `\K` in the regexp is
@@ -501,7 +495,7 @@
 #         /\w*/.match('x')
 #         # => #<MatchData "x">
 #         /\w*/.match('xyz')
-#         # => #<MatchData "xyz">
+#         # => #<MatchData "yz">
 #
 # *   `+` - Matches one or more times:
 #
@@ -714,7 +708,7 @@
 #
 # 1.  The leading subexpression `"` in the pattern matches the first character
 #     `"` in the target string.
-# 2.  The next subexpression `.*` matches the next substring `Quote"` (including
+# 2.  The next subexpression `.*` matches the next substring `Quote“` (including
 #     the trailing double-quote).
 # 3.  Now there is nothing left in the target string to match the trailing
 #     subexpression `"` in the pattern; this would cause the overall match to
@@ -821,8 +815,8 @@
 #     /\P{Alpha}/.match('1') # => #<MatchData "1">
 #     /\P{Alpha}/.match('a') # => nil
 #
-# See [Unicode Properties](rdoc-ref:language/regexp/unicode_properties.rdoc) for
-# regexps based on the numerous properties.
+# See [Unicode Properties](rdoc-ref:regexp/unicode_properties.rdoc) for regexps
+# based on the numerous properties.
 #
 # Some commonly-used properties correspond to POSIX bracket expressions:
 #
@@ -1254,7 +1248,7 @@
 #
 # Regexp matching can apply an optimization to prevent ReDoS attacks. When the
 # optimization is applied, matching time increases linearly (not polynomially or
-# exponentially) in relation to the input size, and a ReDoS attack is not
+# exponentially) in relation to the input size, and a ReDoS attach is not
 # possible.
 #
 # This optimization is applied if the pattern meets these criteria:
@@ -1278,14 +1272,21 @@
 #
 # ## References
 #
-# Read:
+# Read (online PDF books):
 #
-# *   *Mastering Regular Expressions* by Jeffrey E.F. Friedl.
-# *   *Regular Expressions Cookbook* by Jan Goyvaerts & Steven Levithan.
+# *   [Mastering Regular
+#     Expressions](https://ia902508.us.archive.org/10/items/allitebooks-02/Maste
+#     ring%20Regular%20Expressions%2C%203rd%20Edition.pdf) by Jeffrey E.F.
+#     Friedl.
+# *   [Regular Expressions
+#     Cookbook](https://doc.lagout.org/programmation/Regular%20Expressions/Regul
+#     ar%20Expressions%20Cookbook_%20Detailed%20Solutions%20in%20Eight%20Program
+#     ming%20Languages%20%282nd%20ed.%29%20%5BGoyvaerts%20%26%20Levithan%202012-
+#     09-06%5D.pdf) by Jan Goyvaerts & Steven Levithan.
 #
-# Explore, test:
+# Explore, test (interactive online editor):
 #
-# *   [Rubular](https://rubular.com/): interactive online editor.
+# *   [Rubular](https://rubular.com/).
 #
 class Regexp
   # Represents an object's ability to be converted to a `Regexp`.
@@ -1296,9 +1297,6 @@ class Regexp
     def to_regexp: () -> Regexp
   end
 
-  # <!-- rdoc-file=re.c -->
-  # Raised when regexp matching timed out.
-  #
   class TimeoutError < RegexpError
   end
 
@@ -1660,12 +1658,9 @@ class Regexp
 
   # <!--
   #   rdoc-file=re.c
-  #   - encoding -> encoding
+  #   - obj.encoding   -> encoding
   # -->
-  # Returns an Encoding object that represents the encoding of `self`; see
-  # [Encodings](rdoc-ref:encodings.rdoc).
-  #
-  # Related: see [Querying](rdoc-ref:String@Querying).
+  # Returns the Encoding object that represents the encoding of obj.
   #
   def encoding: () -> Encoding
 

data/core/ruby_vm.rbs

@@ -443,7 +443,7 @@ module RubyVM::AbstractSyntaxTree
   #
   # See ::parse for explanation of keyword argument meaning and usage.
   #
-  def self.parse_file: (path string, ?keep_script_lines: bool, ?error_tolerant: bool, ?keep_tokens: bool) -> Node
+  def self.parse_file: (String | ::_ToPath string, ?keep_script_lines: bool, ?error_tolerant: bool, ?keep_tokens: bool) -> Node
 
   # <!--
   #   rdoc-file=ast.rb
@@ -683,13 +683,11 @@ module RubyVM::YJIT
 
   # <!--
   #   rdoc-file=yjit.rb
-  #   - enable(stats: false, log: false, mem_size: nil, call_threshold: nil)
+  #   - enable(stats: false, log: false)
   # -->
   # Enable YJIT compilation. `stats` option decides whether to enable YJIT stats
-  # or not. `log` decides
-  # whether to enable YJIT compilation logging or not. Optional `mem_size` and
-  # `call_threshold` can be
-  # provided to override default configuration.
+  # or not. `compilation_log` decides
+  # whether to enable YJIT compilation logging or not.
   # *   `stats`:
   #     *   `false`: Don't enable stats.
   #     *   `true`: Enable stats. Print stats at exit.

data/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://www.rubydoc.info/github/rubygems/rubygems) (also
 #     available from `gem server`)
 #
 # ## RubyGems Plugins
@@ -48,7 +48,7 @@
 # ## Bugs
 #
 # You can submit bugs to the [RubyGems bug
-# tracker](https://github.com/ruby/rubygems/issues) on GitHub
+# tracker](https://github.com/rubygems/rubygems/issues) on GitHub
 #
 # ## Credits
 #
@@ -83,13 +83,80 @@
 #
 # ## License
 #
-# See [LICENSE.txt](https://github.com/ruby/rubygems/blob/master/LICENSE.txt)
+# See
+# [LICENSE.txt](https://github.com/rubygems/rubygems/blob/master/LICENSE.txt)
 # for permissions.
 #
 # Thanks!
 #
 # -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

data/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://www.rubydoc.info/github/rubygems/rubygems) (also
 #     available from `gem server`)
 #
 # ## RubyGems Plugins
@@ -48,7 +48,7 @@
 # ## Bugs
 #
 # You can submit bugs to the [RubyGems bug
-# tracker](https://github.com/ruby/rubygems/issues) on GitHub
+# tracker](https://github.com/rubygems/rubygems/issues) on GitHub
 #
 # ## Credits
 #
@@ -83,13 +83,80 @@
 #
 # ## License
 #
-# See [LICENSE.txt](https://github.com/ruby/rubygems/blob/master/LICENSE.txt)
+# See
+# [LICENSE.txt](https://github.com/rubygems/rubygems/blob/master/LICENSE.txt)
 # for permissions.
 #
 # Thanks!
 #
 # -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
@@ -137,7 +204,7 @@ module Gem
 
   VERSION: String
 
-  # <!-- rdoc-file=lib/rubygems/win_platform.rb -->
+  # <!-- rdoc-file=lib/rubygems.rb -->
   # An Array of Regexps that match windows Ruby platforms.
   #
   WIN_PATTERNS: Array[Regexp]
@@ -184,7 +251,7 @@ module Gem
 
   # <!--
   #   rdoc-file=lib/rubygems.rb
-  #   - bindir(install_dir = Gem.dir)
+  #   - bindir(install_dir=Gem.dir)
   # -->
   # The path where gem executables are to be installed.
   #
@@ -442,7 +509,7 @@ module Gem
 
   # <!--
   #   rdoc-file=lib/rubygems.rb
-  #   - find_files(glob, check_load_path = true)
+  #   - find_files(glob, check_load_path=true)
   # -->
   # Returns a list of paths matching `glob` that can be used by a gem to pick up
   # features from other gems.  For example:
@@ -459,7 +526,7 @@ module Gem
 
   # <!--
   #   rdoc-file=lib/rubygems.rb
-  #   - find_latest_files(glob, check_load_path = true)
+  #   - find_latest_files(glob, check_load_path=true)
   # -->
   # Returns a list of paths matching `glob` from the latest gems that can be used
   # by a gem to pick up features from other gems.  For example:
@@ -484,7 +551,7 @@ module Gem
 
   # <!--
   #   rdoc-file=lib/rubygems.rb
-  #   - finish_resolve(request_set = Gem::RequestSet.new)
+  #   - finish_resolve(request_set=Gem::RequestSet.new)
   # -->
   #
   def self.finish_resolve: (?RequestSet request_set) -> void
@@ -737,7 +804,7 @@ module Gem
 
   # <!--
   #   rdoc-file=lib/rubygems.rb
-  #   - plugindir(install_dir = Gem.dir)
+  #   - plugindir(install_dir=Gem.dir)
   # -->
   # The path were rubygems plugins are to be installed.
   #
@@ -942,7 +1009,8 @@ module Gem
   #   - source_date_epoch_string()
   # -->
   # If the SOURCE_DATE_EPOCH environment variable is set, returns it's value.
-  # Otherwise, returns DEFAULT_SOURCE_DATE_EPOCH as a string.
+  # Otherwise, returns the time that `Gem.source_date_epoch_string` was first
+  # called in the same format as SOURCE_DATE_EPOCH.
   #
   # NOTE(@duckinator): The implementation is a tad weird because we want to:
   #     1. Make builds reproducible by default, by having this function always
@@ -1086,7 +1154,7 @@ module Gem
   def self.user_home: () -> String
 
   # <!--
-  #   rdoc-file=lib/rubygems/win_platform.rb
+  #   rdoc-file=lib/rubygems.rb
   #   - win_platform?()
   # -->
   # Is this a windows platform?

data/core/rubygems/version.rbs

@@ -180,6 +180,7 @@ module Gem
     #
     #     ver1 = Version.create('1.3.17')   # -> (Version object)
     #     ver2 = Version.create(ver1)       # -> (ver1)
+    #     ver3 = Version.create(nil)        # -> nil
     #
     def self.create: (_ToS | Version input) -> instance
                    | (nil input) -> nil
@@ -198,8 +199,8 @@ module Gem
     #   - <=>(other)
     # -->
     # Compares this version with `other` returning -1, 0, or 1 if the other version
-    # is larger, the same, or smaller than this one. `other` must be an instance of
-    # Gem::Version, comparing with other types may raise an exception.
+    # is larger, the same, or smaller than this one. Attempts to compare to
+    # something that's not a `Gem::Version` or a valid version String return `nil`.
     #
     def <=>: (untyped other) -> Integer?