Merge pull request #1689 from ruby/docs-3.3-rc1

Update docs based on 3.3.0-rc1

Author: soutaro

.github/workflows/comments.yml

@@ -13,7 +13,7 @@ jobs:
     container:
       image: rubylang/ruby:3.2-dev-focal
     env:
-      RUBY_COMMIT: v3_3_0_preview3
+      RUBY_COMMIT: v3_3_0_rc1
     steps:
       - uses: actions/checkout@v4
       - name: Install dependencies

core/comparable.rbs

@@ -8,25 +8,28 @@
 # implement the conventional comparison operators (`<`, `<=`, `==`, `>=`, and
 # `>`) and the method `between?`.
 #
-#     class SizeMatters
+#     class StringSorter
 #       include Comparable
+#
 #       attr :str
 #       def <=>(other)
 #         str.size <=> other.str.size
 #       end
+#
 #       def initialize(str)
 #         @str = str
 #       end
+#
 #       def inspect
 #         @str
 #       end
 #     end
 #
-#     s1 = SizeMatters.new("Z")
-#     s2 = SizeMatters.new("YY")
-#     s3 = SizeMatters.new("XXX")
-#     s4 = SizeMatters.new("WWWW")
-#     s5 = SizeMatters.new("VVVVV")
+#     s1 = StringSorter.new("Z")
+#     s2 = StringSorter.new("YY")
+#     s3 = StringSorter.new("XXX")
+#     s4 = StringSorter.new("WWWW")
+#     s5 = StringSorter.new("VVVVV")
 #
 #     s1 < s2                       #=> true
 #     s4.between?(s1, s3)           #=> false

core/complex.rbs

@@ -1,77 +1,107 @@
 # <!-- rdoc-file=complex.c -->
-# A complex number can be represented as a paired real number with imaginary
-# unit; a+bi.  Where a is real part, b is imaginary part and i is imaginary
-# unit.  Real a equals complex a+0i mathematically.
+# A Complex object houses a pair of values, given when the object is created as
+# either *rectangular coordinates* or *polar coordinates*.
 #
-# You can create a Complex object explicitly with:
+# ## Rectangular Coordinates
 #
-# *   A [complex literal](rdoc-ref:syntax/literals.rdoc@Complex+Literals).
+# The rectangular coordinates of a complex number are called the *real* and
+# *imaginary* parts; see [Complex number
+# definition](https://en.wikipedia.org/wiki/Complex_number#Definition).
 #
+# You can create a Complex object from rectangular coordinates with:
 #
-# You can convert certain objects to Complex objects with:
+# *   A [complex literal](rdoc-ref:doc/syntax/literals.rdoc@Complex+Literals).
+# *   Method Complex.rect.
+# *   Method Kernel#Complex, either with numeric arguments or with certain
+#     string arguments.
+# *   Method String#to_c, for certain strings.
 #
-# *   Method #Complex.
 #
+# Note that each of the stored parts may be a an instance one of the classes
+# Complex, Float, Integer, or Rational; they may be retrieved:
 #
-# Complex object can be created as literal, and also by using Kernel#Complex,
-# Complex::rect, Complex::polar or to_c method.
+# *   Separately, with methods Complex#real and Complex#imaginary.
+# *   Together, with method Complex#rect.
 #
-#     2+1i                 #=> (2+1i)
-#     Complex(1)           #=> (1+0i)
-#     Complex(2, 3)        #=> (2+3i)
-#     Complex.polar(2, 3)  #=> (-1.9799849932008908+0.2822400161197344i)
-#     3.to_c               #=> (3+0i)
 #
-# You can also create complex object from floating-point numbers or strings.
+# The corresponding (computed) polar values may be retrieved:
 #
-#     Complex(0.3)         #=> (0.3+0i)
-#     Complex('0.3-0.5i')  #=> (0.3-0.5i)
-#     Complex('2/3+3/4i')  #=> ((2/3)+(3/4)*i)
-#     Complex('1@2')       #=> (-0.4161468365471424+0.9092974268256817i)
+# *   Separately, with methods Complex#abs and Complex#arg.
+# *   Together, with method Complex#polar.
 #
-#     0.3.to_c             #=> (0.3+0i)
-#     '0.3-0.5i'.to_c      #=> (0.3-0.5i)
-#     '2/3+3/4i'.to_c      #=> ((2/3)+(3/4)*i)
-#     '1@2'.to_c           #=> (-0.4161468365471424+0.9092974268256817i)
 #
-# A complex object is either an exact or an inexact number.
+# ## Polar Coordinates
 #
-#     Complex(1, 1) / 2    #=> ((1/2)+(1/2)*i)
-#     Complex(1, 1) / 2.0  #=> (0.5+0.5i)
+# The polar coordinates of a complex number are called the *absolute* and
+# *argument* parts; see [Complex polar
+# plane](https://en.wikipedia.org/wiki/Complex_number#Polar_complex_plane).
+#
+# You can create a Complex object from polar coordinates with:
+#
+# *   Method Complex.polar.
+# *   Method Kernel#Complex, with certain string arguments.
+# *   Method String#to_c, for certain strings.
+#
+#
+# Note that each of the stored parts may be a an instance one of the classes
+# Complex, Float, Integer, or Rational; they may be retrieved:
+#
+# *   Separately, with methods Complex#abs and Complex#arg.
+# *   Together, with method Complex#polar.
+#
+#
+# The corresponding (computed) rectangular values may be retrieved:
+#
+# *   Separately, with methods Complex#real and Complex#imag.
+# *   Together, with method Complex#rect.
 #
 class Complex < Numeric
   # <!--
   #   rdoc-file=complex.c
-  #   - Complex.polar(abs[, arg])  ->  complex
+  #   - Complex.polar(abs, arg = 0) -> complex
   # -->
-  # Returns a complex object which denotes the given polar form.
+  # Returns a new Complex object formed from the arguments, each of which must be
+  # an instance of Numeric, or an instance of one of its subclasses: Complex,
+  # Float, Integer, Rational; see [Polar
+  # Coordinates](rdoc-ref:Complex@Polar+Coordinates):
   #
-  #     Complex.polar(3, 0)            #=> (3.0+0.0i)
-  #     Complex.polar(3, Math::PI/2)   #=> (1.836909530733566e-16+3.0i)
-  #     Complex.polar(3, Math::PI)     #=> (-3.0+3.673819061467132e-16i)
-  #     Complex.polar(3, -Math::PI/2)  #=> (1.836909530733566e-16-3.0i)
+  #     Complex.polar(3)        # => (3+0i)
+  #     Complex.polar(3, 2.0)   # => (-1.2484405096414273+2.727892280477045i)
+  #     Complex.polar(-3, -2.0) # => (1.2484405096414273+2.727892280477045i)
   #
   def self.polar: (Numeric, ?Numeric) -> Complex
 
   # <!--
   #   rdoc-file=complex.c
-  #   - Complex.rect(real[, imag])         ->  complex
-  #   - Complex.rectangular(real[, imag])  ->  complex
+  #   - Complex.rect(real, imag = 0) -> complex
   # -->
-  # Returns a complex object which denotes the given rectangular form.
+  # Returns a new Complex object formed from the arguments, each of which must be
+  # an instance of Numeric, or an instance of one of its subclasses: Complex,
+  # Float, Integer, Rational; see [Rectangular
+  # Coordinates](rdoc-ref:Complex@Rectangular+Coordinates):
+  #
+  #     Complex.rect(3)             # => (3+0i)
+  #     Complex.rect(3, Math::PI)   # => (3+3.141592653589793i)
+  #     Complex.rect(-3, -Math::PI) # => (-3-3.141592653589793i)
   #
-  #     Complex.rectangular(1, 2)  #=> (1+2i)
+  # Complex.rectangular is an alias for Complex.rect.
   #
   def self.rect: (Numeric, ?Numeric) -> Complex
 
   # <!--
   #   rdoc-file=complex.c
-  #   - Complex.rect(real[, imag])         ->  complex
-  #   - Complex.rectangular(real[, imag])  ->  complex
+  #   - Complex.rect(real, imag = 0) -> complex
   # -->
-  # Returns a complex object which denotes the given rectangular form.
+  # Returns a new Complex object formed from the arguments, each of which must be
+  # an instance of Numeric, or an instance of one of its subclasses: Complex,
+  # Float, Integer, Rational; see [Rectangular
+  # Coordinates](rdoc-ref:Complex@Rectangular+Coordinates):
   #
-  #     Complex.rectangular(1, 2)  #=> (1+2i)
+  #     Complex.rect(3)             # => (3+0i)
+  #     Complex.rect(3, Math::PI)   # => (3+3.141592653589793i)
+  #     Complex.rect(-3, -Math::PI) # => (-3-3.141592653589793i)
+  #
+  # Complex.rectangular is an alias for Complex.rect.
   #
   alias self.rectangular self.rect
 
@@ -462,9 +492,16 @@ class Complex < Numeric
   def real?: () -> false
 
   # <!-- rdoc-file=complex.c -->
-  # Returns a complex object which denotes the given rectangular form.
+  # Returns a new Complex object formed from the arguments, each of which must be
+  # an instance of Numeric, or an instance of one of its subclasses: Complex,
+  # Float, Integer, Rational; see [Rectangular
+  # Coordinates](rdoc-ref:Complex@Rectangular+Coordinates):
+  #
+  #     Complex.rect(3)             # => (3+0i)
+  #     Complex.rect(3, Math::PI)   # => (3+3.141592653589793i)
+  #     Complex.rect(-3, -Math::PI) # => (-3-3.141592653589793i)
   #
-  #     Complex.rectangular(1, 2)  #=> (1+2i)
+  # Complex.rectangular is an alias for Complex.rect.
   #
   def rect: () -> [ Numeric, Numeric ]
 
@@ -559,6 +596,8 @@ class Complex < Numeric
 end
 
 # <!-- rdoc-file=complex.c -->
-# The imaginary unit.
+# Equivalent to `Complex(0, 1)`:
+#
+#     Complex::I # => (0+1i)
 #
 Complex::I: Complex

core/dir.rbs

@@ -362,6 +362,8 @@ class Dir
   #     Dir.exist?('/nosuch')          # => false
   #     Dir.exist?('/example/main.rb') # => false
   #
+  # Same as File.directory?.
+  #
   def self.exist?: (path | io file_name) -> bool
 
   # <!--
@@ -580,14 +582,14 @@ class Dir
   #         Dir.glob('io.?') # => ["io.c"]
   #
   # *   `'[*set*]'`: Matches any one character in the string *set*; behaves like a
-  #     [Regexp character class](rdoc-ref:regexp.rdoc@Character+Classes),
-  #     including set negation (`'[^a-z]'`):
+  #     [Regexp character class](rdoc-ref:Regexp@Character+Classes), including set
+  #     negation (`'[^a-z]'`):
   #
   #         Dir.glob('*.[a-z][a-z]').take(3)
   #         # => ["CONTRIBUTING.md", "COPYING.ja", "KNOWNBUGS.rb"]
   #
   # *   `'{*abc*,*xyz*}'`: Matches either string *abc* or string *xyz*; behaves
-  #     like [Regexp alternation](rdoc-ref:regexp.rdoc@Alternation):
+  #     like [Regexp alternation](rdoc-ref:Regexp@Alternation):
   #
   #         Dir.glob('{LEGAL,BSDL}') # => ["LEGAL", "BSDL"]
   #
@@ -666,9 +668,13 @@ class Dir
   # <!--
   #   rdoc-file=dir.c
   #   - Dir.home(user_name = nil) -> dirpath
-  #   - Dir.home         # => "/home/me"
-  #   - Dir.home('root') # => "/root"
   # -->
+  # Retruns the home directory path of the user specified with `user_name` if it
+  # is not `nil`, or the current login user:
+  #
+  #     Dir.home         # => "/home/me"
+  #     Dir.home('root') # => "/root"
+  #
   # Raises ArgumentError if `user_name` is not a user name.
   #
   def self.home: (?string? user) -> String
@@ -764,7 +770,7 @@ class Dir
   #     Dir.pwd # => "/"
   #     dir = Dir.new('example')
   #     dir.chdir
-  #     dir.pwd # => "/example"
+  #     Dir.pwd # => "/example"
   #
   def chdir: () -> Integer
            | [T] { () -> T } -> T

core/fiber.rbs

@@ -373,14 +373,21 @@ class Fiber < Object
   #   rdoc-file=cont.c
   #   - fiber.kill -> nil
   # -->
-  # Terminates `fiber` by raising an uncatchable exception, returning the
-  # terminated Fiber.
+  # Terminates the fiber by raising an uncatchable exception. It only terminates
+  # the given fiber and no other fiber, returning `nil` to another fiber if that
+  # fiber was calling #resume or #transfer.
+  #
+  # `Fiber#kill` only interrupts another fiber when it is in Fiber.yield. If
+  # called on the current fiber then it raises that exception at the `Fiber#kill`
+  # call site.
   #
   # If the fiber has not been started, transition directly to the terminated
   # state.
   #
   # If the fiber is already terminated, does nothing.
   #
+  # Raises FiberError if called on a fiber belonging to another thread.
+  #
   def kill: () -> nil
 
   # <!--
@@ -403,6 +410,8 @@ class Fiber < Object
   # parameter is an array of callback information. Exceptions are caught by the
   # `rescue` clause of `begin...end` blocks.
   #
+  # Raises `FiberError` if called on a Fiber belonging to another `Thread`.
+  #
   def raise: (?string msg) -> untyped
            | (_Exception, ?string msg, ?Array[string] backtrace) -> untyped
 

core/file.rbs

@@ -931,8 +931,15 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - birthtime(p1)
+  #   - File.birthtime(file_name)  -> time
   # -->
+  # Returns the birth time for the named file.
+  #
+  # *file_name* can be an IO object.
+  #
+  #     File.birthtime("testfile")   #=> Wed Apr 09 08:53:13 CDT 2003
+  #
+  # If the platform doesn't have birthtime, raises NotImplementedError.
   #
   def self.birthtime: (string | _ToPath | IO file_name) -> Time
 
@@ -1914,8 +1921,11 @@ class File < IO
 
   # <!--
   #   rdoc-file=file.c
-  #   - size()
+  #   - file.size    -> integer
   # -->
+  # Returns the size of *file* in bytes.
+  #
+  #     File.new("testfile").size   #=> 66
   #
   def size: () -> Integer
 
@@ -2504,19 +2514,12 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - File.directory?(path) -> true or false
+  #   - stat.directory?   -> true or false
   # -->
-  # With string `object` given, returns `true` if `path` is a string path leading
-  # to a directory, or to a symbolic link to a directory; `false` otherwise:
+  # Returns `true` if *stat* is a directory, `false` otherwise.
   #
-  #     File.directory?('.')              # => true
-  #     File.directory?('foo')            # => false
-  #     File.symlink('.', 'dirlink')      # => 0
-  #     File.directory?('dirlink')        # => true
-  #     File.symlink('t,txt', 'filelink') # => 0
-  #     File.directory?('filelink')       # => false
-  #
-  # Argument `path` can be an IO object.
+  #     File.stat("testfile").directory?   #=> false
+  #     File.stat(".").directory?          #=> true
   #
   def directory?: () -> bool