From 64fbd0a7a8e6722a0f26bd7e00870e678723db5a Mon Sep 17 00:00:00 2001 From: Soutaro Matsumoto Date: Fri, 27 Dec 2024 13:35:54 +0900 Subject: [PATCH] Update docs --- .github/workflows/comments.yml | 4 +- core/exception.rbs | 185 ++++++++++++++++++++++++++------- core/kernel.rbs | 70 ++++++++++--- core/ractor.rbs | 3 + core/regexp.rbs | 6 +- core/ruby_vm.rbs | 16 +-- stdlib/monitor/0/monitor.rbs | 17 ++- 7 files changed, 233 insertions(+), 68 deletions(-) diff --git a/.github/workflows/comments.yml b/.github/workflows/comments.yml index 154a422b3..36a923590 100644 --- a/.github/workflows/comments.yml +++ b/.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 diff --git a/core/exception.rbs b/core/exception.rbs index d428d48ab..b8b28030b 100644 --- a/core/exception.rbs +++ b/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 '
'"] + # loc = ex.backtrace.first + # p loc.class + # # String # end - # # => ["(irb):132:in `/'", "(irb):132:in `'"] + # + # 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 '
'"] + # 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 `'"] + # + # 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 '
'"] + # p ex.backtrace_locations + # # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '
'"] + # 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 '
'"] + # p ex.backtrace_locations + # # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '
'"] + # 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 `
'"] - # ["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 `
'"] + # ["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 '
'"] + # ["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 '
'"] # # An overriding method should be careful with ANSI code enhancements; see # [Messages](rdoc-ref:exceptions.md@Messages). diff --git a/core/kernel.rbs b/core/kernel.rbs index 6a5d91f2d..262719c46 100644 --- a/core/kernel.rbs +++ b/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. diff --git a/core/ractor.rbs b/core/ractor.rbs index eb50e1229..7e992d1b1 100644 --- a/core/ractor.rbs +++ b/core/ractor.rbs @@ -1053,6 +1053,9 @@ class Ractor # end # class RemoteError < Ractor::Error + # + # The Ractor an uncaught exception is raised in. + # def ractor: () -> Ractor end diff --git a/core/regexp.rbs b/core/regexp.rbs index f713b907d..6f5eb1df3 100644 --- a/core/regexp.rbs +++ b/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: # diff --git a/core/ruby_vm.rbs b/core/ruby_vm.rbs index db629d3ab..623790ebc 100644 --- a/core/ruby_vm.rbs +++ b/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 diff --git a/stdlib/monitor/0/monitor.rbs b/stdlib/monitor/0/monitor.rbs index de4806c0c..a17b67deb 100644 --- a/stdlib/monitor/0/monitor.rbs +++ b/stdlib/monitor/0/monitor.rbs @@ -12,15 +12,17 @@ class Monitor # + # Enters exclusive section. # def enter: () -> nil # + # Leaves exclusive section. # def exit: () -> nil @@ -77,20 +79,25 @@ class Monitor # rdoc-file=ext/monitor/lib/monitor.rb # - new_cond() # --> + # Creates a new MonitorMixin::ConditionVariable associated with the Monitor + # object. # def new_cond: () -> ::MonitorMixin::ConditionVariable # + # Enters exclusive section and executes the block. Leaves the exclusive section + # automatically when the block exits. See example under `MonitorMixin`. # def synchronize: [T] () { () -> T } -> T # + # Attempts to enter exclusive section. Returns `false` if lock fails. # def try_enter: () -> bool @@ -279,6 +286,8 @@ module MonitorMixin # rdoc-file=ext/monitor/lib/monitor.rb # - mon_check_owner() # --> + # Ensures that the MonitorMixin is owned by the current thread, otherwise raises + # an exception. # def mon_check_owner: () -> nil