Merge pull request #2208 from ruby/3.4-docs

Update docs based on Ruby 3.4.1

.github/workflows/comments.yml

@@ -10,8 +10,8 @@ on:
 jobs:
   comments:
     runs-on: "ubuntu-latest"
-    env:
-      RUBY_COMMIT: 1b0c46daed9186b82ab4fef1a4ab225afe582ee6
+    # env:
+    #   RUBY_COMMIT: 1b0c46daed9186b82ab4fef1a4ab225afe582ee6
     steps:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1

core/exception.rbs

@@ -99,24 +99,31 @@ class Exception
   #   rdoc-file=error.c
   #   - backtrace -> array or nil
   # -->
-  # Returns a backtrace value for `self`; the returned value depends on the form
-  # of the stored backtrace value:
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of strings.
   #
-  # *   Array of Thread::Backtrace::Location objects: returns the array of strings
-  #     given by `Exception#backtrace_locations.map {|loc| loc.to_s }`. This is
-  #     the normal case, where the backtrace value was stored by Kernel#raise.
-  # *   Array of strings: returns that array. This is the unusual case, where the
-  #     backtrace value was explicitly stored as an array of strings.
-  # *   `nil`: returns `nil`.
+  # Example (assuming the code is stored in the file named `t.rb`):
   #
-  # Example:
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
   #
   #     begin
-  #       1 / 0
-  #     rescue => x
-  #       x.backtrace.take(2)
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace.first
+  #       p loc.class
+  #       # String
   #     end
-  #     # => ["(irb):132:in `/'", "(irb):132:in `<top (required)>'"]
+  #
+  # The value returned by this method migth be adjusted when raising (see
+  # Kernel#raise), or during intermediate handling by #set_backtrace.
+  #
+  # See also #backtrace_locations that provide the same value, as structured
+  # objects. (Note though that two values might not be consistent with each other
+  # when backtraces are manually adjusted.)
   #
   # see [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -126,20 +133,37 @@ class Exception
   #   rdoc-file=error.c
   #   - backtrace_locations -> array or nil
   # -->
-  # Returns a backtrace value for `self`; the returned value depends on the form
-  # of the stored backtrace value:
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of Thread::Backtrace::Location instances.
   #
-  # *   Array of Thread::Backtrace::Location objects: returns that array.
-  # *   Array of strings or `nil`: returns `nil`.
+  # Example (assuming the code is stored in the file named `t.rb`):
   #
-  # Example:
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
   #
   #     begin
-  #       1 / 0
-  #     rescue => x
-  #       x.backtrace_locations.take(2)
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace_locations
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace_locations.first
+  #       p loc.class
+  #       # Thread::Backtrace::Location
+  #       p loc.path
+  #       # "t.rb"
+  #       p loc.lineno
+  #       # 2
+  #       p loc.label
+  #       # "Integer#/"
   #     end
-  #     # => ["(irb):150:in `/'", "(irb):150:in `<top (required)>'"]
+  #
+  # The value returned by this method might be adjusted when raising (see
+  # Kernel#raise), or during intermediate handling by #set_backtrace.
+  #
+  # See also #backtrace that provide the same value as an array of strings. (Note
+  # though that two values might not be consistent with each other when backtraces
+  # are manually adjusted.)
   #
   # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -294,15 +318,100 @@ class Exception
   #   rdoc-file=error.c
   #   - set_backtrace(value) -> value
   # -->
-  # Sets the backtrace value for `self`; returns the given +value:
+  # Sets the backtrace value for `self`; returns the given `value`.
   #
-  #     x = RuntimeError.new('Boom')
-  #     x.set_backtrace(%w[foo bar baz]) # => ["foo", "bar", "baz"]
-  #     x.backtrace                      # => ["foo", "bar", "baz"]
+  # The `value` might be:
   #
-  # The given `value` must be an array of strings, a single string, or `nil`.
+  # *   an array of Thread::Backtrace::Location;
+  # *   an array of String instances;
+  # *   a single String instance; or
+  # *   `nil`.
+  #
+  # Using array of Thread::Backtrace::Location is the most consistent option: it
+  # sets both #backtrace and #backtrace_locations. It should be preferred when
+  # possible. The suitable array of locations can be obtained from
+  # Kernel#caller_locations, copied from another error, or just set to the
+  # adjusted result of the current error's #backtrace_locations:
+  #
+  #     require 'json'
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)  # test.rb, line 4
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(ex.backtrace_locations[2...])
+  #       raise
+  #     end
   #
-  # Does not affect the value returned by #backtrace_locations.
+  #     parse_payload('{"wrong: "json"')
+  #     # test.rb:4:in 'Object#parse_payload': unexpected token at '{"wrong: "json"' (JSON::ParserError)
+  #     #
+  #     # An error points to the body of parse_payload method,
+  #     # hiding the parts of the backtrace related to the internals
+  #     # of the "json" library
+  #
+  #     # The error has both #backtace and #backtrace_locations set
+  #     # consistently:
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #     end
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only #backtrace is affected:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(["dsl.rb:34", "framework.rb:1"])
+  #       # The error have the new value in #backtrace:
+  #       p ex.backtrace
+  #       # ["dsl.rb:34", "framework.rb:1"]
+  #
+  #       # but the original one in #backtrace_locations
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # Calling #set_backtrace with `nil` clears up #backtrace but doesn't affect
+  # #backtrace_locations:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       p ex.backtrace
+  #       # nil
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # On reraising of such an exception, both #backtrace and #backtrace_locations is
+  # set to the place of reraising:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       raise # test.rb, line 7
+  #     end
+  #
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #     end
   #
   # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -358,16 +467,16 @@ class Exception
   # Output:
   #
   #     "divided by 0"
-  #     ["t.rb:3:in `/': divided by 0 (ZeroDivisionError)",
-  #      "\tfrom t.rb:3:in `baz'",
-  #      "\tfrom t.rb:10:in `bar'",
-  #      "\tfrom t.rb:11:in `foo'",
-  #      "\tfrom t.rb:12:in `<main>'"]
-  #     ["t.rb:3:in `/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
-  #      "\tfrom t.rb:3:in `baz'",
-  #      "\tfrom t.rb:10:in `bar'",
-  #      "\tfrom t.rb:11:in `foo'",
-  #      "\tfrom t.rb:12:in `<main>'"]
+  #     ["t.rb:3:in 'Integer#/': divided by 0 (ZeroDivisionError)",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#foo'",
+  #      "\tfrom t.rb:12:in '<main>'"]
+  #     ["t.rb:3:in 'Integer#/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#foo'",
+  #      "\tfrom t.rb:12:in '<main>'"]
   #
   # An overriding method should be careful with ANSI code enhancements; see
   # [Messages](rdoc-ref:exceptions.md@Messages).

core/kernel.rbs

@@ -936,16 +936,37 @@ module Kernel : BasicObject
   #
   # See [Messages](rdoc-ref:exceptions.md@Messages).
   #
-  # Argument `backtrace` sets the stored backtrace in the new exception, which may
-  # be retrieved by method Exception#backtrace; the backtrace must be an array of
-  # strings or `nil`:
+  # Argument `backtrace` might be used to modify the backtrace of the new
+  # exception, as reported by Exception#backtrace and
+  # Exception#backtrace_locations; the backtrace must be an array of
+  # Thread::Backtrace::Location, an array of strings, a single string, or `nil`.
+  #
+  # Using the array of Thread::Backtrace::Location instances is the most
+  # consistent option and should be preferred when possible. The necessary value
+  # might be obtained from #caller_locations, or copied from
+  # Exception#backtrace_locations of another error:
   #
   #     begin
-  #       raise(StandardError, 'Boom', %w[foo bar baz])
-  #     rescue => x
-  #       p x.backtrace
+  #       do_some_work()
+  #     rescue ZeroDivisionError => ex
+  #       raise(LogicalError, "You have an error in your math", ex.backtrace_locations)
+  #     end
+  #
+  # The ways, both Exception#backtrace and Exception#backtrace_locations of the
+  # raised error are set to the same backtrace.
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only Exception#backtrace is set:
+  #
+  #     begin
+  #       raise(StandardError, 'Boom', %w[dsl.rb:3 framework.rb:1])
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # => ["dsl.rb:3", "framework.rb:1"]
+  #       p ex.backtrace_locations
+  #       # => nil
   #     end
-  #     # => ["foo", "bar", "baz"]
   #
   # If argument `backtrace` is not given, the backtrace is set according to an
   # array of Thread::Backtrace::Location objects, as derived from the call stack.
@@ -1021,16 +1042,37 @@ module Kernel : BasicObject
   #
   # See [Messages](rdoc-ref:exceptions.md@Messages).
   #
-  # Argument `backtrace` sets the stored backtrace in the new exception, which may
-  # be retrieved by method Exception#backtrace; the backtrace must be an array of
-  # strings or `nil`:
+  # Argument `backtrace` might be used to modify the backtrace of the new
+  # exception, as reported by Exception#backtrace and
+  # Exception#backtrace_locations; the backtrace must be an array of
+  # Thread::Backtrace::Location, an array of strings, a single string, or `nil`.
+  #
+  # Using the array of Thread::Backtrace::Location instances is the most
+  # consistent option and should be preferred when possible. The necessary value
+  # might be obtained from #caller_locations, or copied from
+  # Exception#backtrace_locations of another error:
   #
   #     begin
-  #       raise(StandardError, 'Boom', %w[foo bar baz])
-  #     rescue => x
-  #       p x.backtrace
+  #       do_some_work()
+  #     rescue ZeroDivisionError => ex
+  #       raise(LogicalError, "You have an error in your math", ex.backtrace_locations)
+  #     end
+  #
+  # The ways, both Exception#backtrace and Exception#backtrace_locations of the
+  # raised error are set to the same backtrace.
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only Exception#backtrace is set:
+  #
+  #     begin
+  #       raise(StandardError, 'Boom', %w[dsl.rb:3 framework.rb:1])
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # => ["dsl.rb:3", "framework.rb:1"]
+  #       p ex.backtrace_locations
+  #       # => nil
   #     end
-  #     # => ["foo", "bar", "baz"]
   #
   # If argument `backtrace` is not given, the backtrace is set according to an
   # array of Thread::Backtrace::Location objects, as derived from the call stack.

core/ractor.rbs

@@ -1053,6 +1053,9 @@ class Ractor
   #     end
   #
   class RemoteError < Ractor::Error
+    # <!-- rdoc-file=ractor.rb -->
+    # The Ractor an uncaught exception is raised in.
+    #
     def ractor: () -> Ractor
   end
 

core/regexp.rbs

@@ -836,8 +836,10 @@
 # These are also commonly used:
 #
 # *   `/\p{Emoji}/`: Unicode emoji.
-# *   `/\p{Graph}/`: Non-blank character (excludes spaces, control characters,
-#     and similar).
+# *   `/\p{Graph}/`: Characters excluding `/\p{Cntrl}/` and `/\p{Space}/`. Note
+#     that invisible characters under the Unicode
+#     ["Format"](https://www.compart.com/en/unicode/category/Cf) category are
+#     included.
 # *   `/\p{Word}/`: A member in one of these Unicode character categories (see
 #     below) or having one of these Unicode properties:
 #

core/ruby_vm.rbs

@@ -688,14 +688,14 @@ module RubyVM::YJIT
   # Enable YJIT compilation. `stats` option decides whether to enable YJIT stats
   # 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.
-  # * `:quiet`: Enable stats. Do not print stats at exit.
-  # `log`:
-  # * `false`: Don't enable the log.
-  # * `true`: Enable the log. Print log at exit.
-  # * `:quiet`: Enable the log. Do not print log at exit.
+  # *   `stats`:
+  #     *   `false`: Don't enable stats.
+  #     *   `true`: Enable stats. Print stats at exit.
+  #     *   `:quiet`: Enable stats. Do not print stats at exit.
+  # *   `log`:
+  #     *   `false`: Don't enable the log.
+  #     *   `true`: Enable the log. Print log at exit.
+  #     *   `:quiet`: Enable the log. Do not print log at exit.
   #
   def self.enable: (?stats: false | true | :quiet) -> void