From 9ffa3be7a5efc3a7ce15abcd2a91bcdeebc7e21e Mon Sep 17 00:00:00 2001 From: Soutaro Matsumoto Date: Mon, 23 Dec 2024 12:31:48 +0900 Subject: [PATCH] Update docs as of 15:42 JST --- .github/workflows/comments.yml | 2 +- core/array.rbs | 126 ++++++------ core/complex.rbs | 2 +- core/encoding.rbs | 26 --- core/errors.rbs | 4 + core/exception.rbs | 4 +- core/file.rbs | 7 - core/gc.rbs | 22 ++- core/hash.rbs | 4 +- core/kernel.rbs | 2 +- core/nil_class.rbs | 3 + core/numeric.rbs | 2 +- core/proc.rbs | 90 ++++++++- core/regexp.rbs | 4 +- core/ruby_vm.rbs | 2 +- core/rubygems/errors.rbs | 4 +- core/rubygems/rubygems.rbs | 4 +- core/string.rbs | 262 +++++++++++++------------ core/time.rbs | 4 + core/trace_point.rbs | 221 ++++++++++----------- stdlib/date/0/date.rbs | 46 ++--- stdlib/net-http/0/net-http.rbs | 49 ++--- stdlib/rdoc/0/rdoc.rbs | 18 +- stdlib/resolv/0/resolv.rbs | 6 +- stdlib/securerandom/0/securerandom.rbs | 7 + stdlib/socket/0/socket.rbs | 37 +--- stdlib/socket/0/tcp_socket.rbs | 38 +--- 27 files changed, 516 insertions(+), 480 deletions(-) diff --git a/.github/workflows/comments.yml b/.github/workflows/comments.yml index 801454758..74f7f434e 100644 --- a/.github/workflows/comments.yml +++ b/.github/workflows/comments.yml @@ -11,7 +11,7 @@ jobs: comments: runs-on: "ubuntu-latest" env: - RUBY_COMMIT: v3_4_0_rc1 + RUBY_COMMIT: 1b0c46daed9186b82ab4fef1a4ab225afe582ee6 steps: - uses: actions/checkout@v4 - uses: ruby/setup-ruby@v1 diff --git a/core/array.rbs b/core/array.rbs index d2e5b963d..a368c1c23 100644 --- a/core/array.rbs +++ b/core/array.rbs @@ -70,18 +70,20 @@ # # You can create an Array object explicitly with: # -# * An [array literal](rdoc-ref:literals.rdoc@Array+Literals): +# * An [array literal](rdoc-ref:syntax/literals.rdoc@Array+Literals): # # [1, 'one', :one, [2, 'two', :two]] # -# * A [%w or %W: string-array -# Literal](rdoc-ref:literals.rdoc@25w+and+-25W-3A+String-Array+Literals): +# * A [%w or %W string-array +# Literal](rdoc-ref:syntax/literals.rdoc@25w+and+-25W-3A+String-Array+Litera +# ls): # # %w[foo bar baz] # => ["foo", "bar", "baz"] # %w[1 % *] # => ["1", "%", "*"] # -# * A [%i pr %I: symbol-array -# Literal](rdoc-ref:literals.rdoc@25i+and+-25I-3A+Symbol-Array+Literals): +# * A [%i or %I symbol-array +# Literal](rdoc-ref:syntax/literals.rdoc@25i+and+-25I-3A+Symbol-Array+Litera +# ls): # # %i[foo bar baz] # => [:foo, :bar, :baz] # %i[1 % *] # => [:"1", :%, :*] @@ -677,7 +679,7 @@ class Array[unchecked out Elem] < Object # When string argument `string_separator` is given, equivalent to # `self.join(string_separator)`: # - # [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}" + # [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {foo: 0}" # def *: (string str) -> ::String | (int int) -> ::Array[Elem] @@ -1293,13 +1295,13 @@ class Array[unchecked out Elem] < Object # # When a block and a positive [integer-convertible # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects) - # argument `n` (`0 < n <= self.size`) are given, calls the block with all - # `n`-tuple combinations of `self`; returns `self`: + # argument `count` (`0 < count <= self.size`) are given, calls the block with + # each combination of `self` of size `count`; returns `self`: # # a = %w[a b c] # => ["a", "b", "c"] # a.combination(2) {|combination| p combination } # => ["a", "b", "c"] @@ -1312,7 +1314,7 @@ class Array[unchecked out Elem] < Object # # The order of the yielded combinations is not guaranteed. # - # When `n` is zero, calls the block once with a new empty array: + # When `count` is zero, calls the block once with a new empty array: # # a.combination(0) {|combination| p combination } # [].combination(0) {|combination| p combination } @@ -1322,8 +1324,8 @@ class Array[unchecked out Elem] < Object # [] # [] # - # When `n` is negative or larger than `self.size` and `self` is non-empty, does - # not call the block: + # When `count` is negative or larger than `self.size` and `self` is non-empty, + # does not call the block: # # a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"] # a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"] @@ -1583,10 +1585,10 @@ class Array[unchecked out Elem] < Object # - # Returns a new array containing all but the first `n` element of `self`, where - # `n` is a non-negative Integer; does not modify `self`. + # Returns a new array containing all but the first `count` element of `self`, + # where `count` is a non-negative integer; does not modify `self`. # # Examples: # @@ -1766,34 +1768,34 @@ class Array[unchecked out Elem] < Object # # With no block given, returns a new array containing the elements of `self` at - # the offsets given by `indexes`; each of the `indexes` must be an + # the offsets specified by `indexes`. Each of the `indexes` must be an # [integer-convertible # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects): # # a = [:foo, :bar, :baz] - # a.fetch_values(3, 1) # => [:baz, :foo] - # a.fetch_values(3.1, 1) # => [:baz, :foo] + # a.fetch_values(2, 0) # => [:baz, :foo] + # a.fetch_values(2.1, 0) # => [:baz, :foo] # a.fetch_values # => [] # # For a negative index, counts backwards from the end of the array: # - # a.fetch_values([-2, -1]) # [:bar, :baz] + # a.fetch_values(-2, -1) # [:bar, :baz] # # When no block is given, raises an exception if any index is out of range. # # With a block given, for each index: # - # * If the index in in range, uses an element of `self` (as above). - # * Otherwise calls, the block with the index, and uses the block's return + # * If the index is in range, uses an element of `self` (as above). + # * Otherwise, calls the block with the index and uses the block's return # value. # # Example: # # a = [:foo, :bar, :baz] - # a.fetch_values(1, 0, 42, 777) {|index| index.to_s} + # a.fetch_values(1, 0, 42, 777) { |index| index.to_s } # # => [:bar, :foo, "42", "777"] # # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching). @@ -2070,7 +2072,7 @@ class Array[unchecked out Elem] < Object # # [].first # => nil # - # With non-negative integer argument `count` given, returns the first `count` + # With a non-negative integer argument `count` given, returns the first `count` # elements (as available) in a new array: # # a.first(0) # => [] @@ -2348,7 +2350,7 @@ class Array[unchecked out Elem] < Object # # Returns elements from `self`, or `nil`; `self` is not modified. # @@ -2359,8 +2361,8 @@ class Array[unchecked out Elem] < Object # a # => [:foo, "bar", 2] # [].last # => nil # - # With non-negative integer argument `n` is given, returns a new array - # containing the trailing `n` elements of `self`, as available: + # With non-negative integer argument `count` given, returns a new array + # containing the trailing `count` elements of `self`, as available: # # a = [:foo, 'bar', 2] # a.last(2) # => ["bar", 2] @@ -2419,9 +2421,9 @@ class Array[unchecked out Elem] < Object # # Returns one of the following: # @@ -2438,8 +2440,8 @@ class Array[unchecked out Elem] < Object # # [1, 0, 3, 2].max # => 3 # - # With non-negative numeric argument `n` and no block, returns a new array with - # at most `n` elements, in descending order, per method `#<=>`: + # With non-negative numeric argument `count` and no block, returns a new array + # with at most `count` elements, in descending order, per method `#<=>`: # # [1, 0, 3, 2].max(3) # => [3, 2, 1] # [1, 0, 3, 2].max(3.0) # => [3, 2, 1] @@ -2454,8 +2456,8 @@ class Array[unchecked out Elem] < Object # ['0', '', '000', '00'].max {|a, b| a.size <=> b.size } # # => "000" # - # With non-negative numeric argument `n` and a block, returns a new array with - # at most `n` elements, in descending order, per the block: + # With non-negative numeric argument `count` and a block, returns a new array + # with at most `count` elements, in descending order, per the block: # # ['0', '', '000', '00'].max(2) {|a, b| a.size <=> b.size } # # => ["000", "00"] @@ -2470,9 +2472,9 @@ class Array[unchecked out Elem] < Object # # Returns one of the following: # @@ -2489,8 +2491,8 @@ class Array[unchecked out Elem] < Object # # [1, 0, 3, 2].min # => 0 # - # With non-negative numeric argument `n` and no block, returns a new array with - # at most `n` elements, in ascending order, per method `#<=>`: + # With non-negative numeric argument `count` and no block, returns a new array + # with at most `count` elements, in ascending order, per method `#<=>`: # # [1, 0, 3, 2].min(3) # => [0, 1, 2] # [1, 0, 3, 2].min(3.0) # => [0, 1, 2] @@ -2505,8 +2507,8 @@ class Array[unchecked out Elem] < Object # ['0', '', '000', '00'].min {|a, b| a.size <=> b.size } # # => "" # - # With non-negative numeric argument `n` and a block, returns a new array with - # at most `n` elements, in ascending order, per the block: + # With non-negative numeric argument `count` and a block, returns a new array + # with at most `count` elements, in ascending order, per the block: # # ['0', '', '000', '00'].min(2) {|a, b| a.size <=> b.size } # # => ["", "0"] @@ -2623,15 +2625,15 @@ class Array[unchecked out Elem] < Object # # Iterates over permutations of the elements of `self`; the order of # permutations is indeterminate. # - # With a block and an in-range positive integer argument `n` (`0 < n <= - # self.size`) given, calls the block with each `n`-tuple permutations of `self`; - # returns `self`: + # With a block and an in-range positive integer argument `count` (`0 < count <= + # self.size`) given, calls the block with each permutation of `self` of size + # `count`; returns `self`: # # a = [0, 1, 2] # perms = [] @@ -2646,14 +2648,14 @@ class Array[unchecked out Elem] < Object # a.permutation(3) {|perm| perms.push(perm) } # perms # => [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]] # - # When `n` is zero, calls the block once with a new empty array: + # When `count` is zero, calls the block once with a new empty array: # # perms = [] # a.permutation(0) {|perm| perms.push(perm) } # perms # => [[]] # - # When `n` is out of range (negative or larger than `self.size`), does not call - # the block: + # When `count` is out of range (negative or larger than `self.size`), does not + # call the block: # # a.permutation(-1) {|permutation| fail 'Cannot happen' } # a.permutation(4) {|permutation| fail 'Cannot happen' } @@ -3092,7 +3094,7 @@ class Array[unchecked out Elem] < Object # - sample(random: Random) -> object # - sample(count, random: Random) -> new_ary # --> - # Returns random elements from `self`, as selected by the object given by + # Returns random elements from `self`, as selected by the object given by the # keyword argument `random`. # # With no argument `count` given, returns one random element from `self`: @@ -3105,7 +3107,7 @@ class Array[unchecked out Elem] < Object # # [].sample # => nil # - # With non-negative numeric argument `count` given, returns a new array + # With a non-negative numeric argument `count` given, returns a new array # containing `count` random elements from `self`: # # a.sample(3) # => [8, 9, 2] @@ -3127,12 +3129,12 @@ class Array[unchecked out Elem] < Object # # a.sample(50) # => [6, 4, 1, 8, 5, 9, 0, 2, 3, 7] # - # The object given with keyword argument `random` is used as the random number - # generator: + # The object given with the keyword argument `random` is used as the random + # number generator: # # a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - # a.sample(random: Random.new(1)) #=> 6 - # a.sample(4, random: Random.new(1)) #=> [6, 10, 9, 2] + # a.sample(random: Random.new(1)) # => 6 + # a.sample(4, random: Random.new(1)) # => [6, 10, 9, 2] # # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching). # @@ -3229,7 +3231,7 @@ class Array[unchecked out Elem] < Object # - shuffle(random: Random) -> new_array # --> # Returns a new array containing all elements from `self` in a random order, as - # selected by the object given by keyword argument `random`: + # selected by the object given by the keyword argument `random`: # # a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] # a.shuffle # => [0, 8, 1, 9, 6, 3, 4, 7, 2, 5] @@ -3241,8 +3243,8 @@ class Array[unchecked out Elem] < Object # a.shuffle # => [1, 0, 1, 1, 0, 0, 1, 0, 0, 1] # a.shuffle # => [1, 1, 0, 0, 0, 1, 1, 0, 0, 1] # - # The object given with keyword argument `random` is used as the random number - # generator. + # The object given with the keyword argument `random` is used as the random + # number generator. # # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching). # @@ -3253,20 +3255,20 @@ class Array[unchecked out Elem] < Object # - shuffle!(random: Random) -> self # --> # Shuffles all elements in `self` into a random order, as selected by the object - # given by keyword argument `random`; returns `self`: + # given by the keyword argument `random`. Returns `self`: # # a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] # a.shuffle! # => [5, 3, 8, 7, 6, 1, 9, 4, 2, 0] # a.shuffle! # => [9, 4, 0, 6, 2, 8, 1, 5, 3, 7] # - # Duplicate elements are included: + # Duplicate elements are included: # # a = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1] # a.shuffle! # => [1, 0, 0, 1, 1, 0, 1, 0, 0, 1] # a.shuffle! # => [0, 1, 0, 1, 1, 0, 1, 0, 1, 0] # - # The object given with keyword argument `random` is used as the random number - # generator. + # The object given with the keyword argument `random` is used as the random + # number generator. # # Related: see [Methods for Assigning](rdoc-ref:Array@Methods+for+Assigning). # @@ -3922,7 +3924,7 @@ class Array[unchecked out Elem] < Object # # With no block given, combines `self` with the collection of `other_arrays`; # returns a new array of sub-arrays: diff --git a/core/complex.rbs b/core/complex.rbs index d00091433..5977828df 100644 --- a/core/complex.rbs +++ b/core/complex.rbs @@ -11,7 +11,7 @@ # # You can create a Complex object from rectangular coordinates with: # -# * A [complex literal](rdoc-ref:doc/syntax/literals.rdoc@Complex+Literals). +# * A [complex literal](rdoc-ref:syntax/literals.rdoc@Complex+Literals). # * Method Complex.rect. # * Method Kernel#Complex, either with numeric arguments or with certain # string arguments. diff --git a/core/encoding.rbs b/core/encoding.rbs index e3633bc8f..499ae039e 100644 --- a/core/encoding.rbs +++ b/core/encoding.rbs @@ -1302,96 +1302,70 @@ class Encoding::Converter < Object end # -# AFTER_OUTPUT -# # Stop converting after some output is complete but before all of the input was # consumed. See primitive_convert for an example. # Encoding::Converter::AFTER_OUTPUT: Integer # -# CRLF_NEWLINE_DECORATOR -# # Decorator for converting LF to CRLF # Encoding::Converter::CRLF_NEWLINE_DECORATOR: Integer # -# CR_NEWLINE_DECORATOR -# # Decorator for converting LF to CR # Encoding::Converter::CR_NEWLINE_DECORATOR: Integer # -# INVALID_MASK -# # Mask for invalid byte sequences # Encoding::Converter::INVALID_MASK: Integer # -# INVALID_REPLACE -# # Replace invalid byte sequences # Encoding::Converter::INVALID_REPLACE: Integer # -# PARTIAL_INPUT -# # Indicates the source may be part of a larger string. See primitive_convert # for an example. # Encoding::Converter::PARTIAL_INPUT: Integer # -# UNDEF_HEX_CHARREF -# # Replace byte sequences that are undefined in the destination encoding with an # XML hexadecimal character reference. This is valid for XML conversion. # Encoding::Converter::UNDEF_HEX_CHARREF: Integer # -# UNDEF_MASK -# # Mask for a valid character in the source encoding but no related character(s) # in destination encoding. # Encoding::Converter::UNDEF_MASK: Integer # -# UNDEF_REPLACE -# # Replace byte sequences that are undefined in the destination encoding. # Encoding::Converter::UNDEF_REPLACE: Integer # -# UNIVERSAL_NEWLINE_DECORATOR -# # Decorator for converting CRLF and CR to LF # Encoding::Converter::UNIVERSAL_NEWLINE_DECORATOR: Integer # -# XML_ATTR_CONTENT_DECORATOR -# # Escape as XML AttValue # Encoding::Converter::XML_ATTR_CONTENT_DECORATOR: Integer # -# XML_ATTR_QUOTE_DECORATOR -# # Escape as XML AttValue # Encoding::Converter::XML_ATTR_QUOTE_DECORATOR: Integer # -# XML_TEXT_DECORATOR -# # Escape as XML CharData # Encoding::Converter::XML_TEXT_DECORATOR: Integer diff --git a/core/errors.rbs b/core/errors.rbs index f6177d9f7..b4cb039f6 100644 --- a/core/errors.rbs +++ b/core/errors.rbs @@ -188,6 +188,10 @@ end # # LoadError: no such file to load -- this/file/does/not/exist # +# +# for RubyGems without Bundler environment. If loading library is not part of +# the default gems and the bundled gems, warn it. +# class LoadError < ScriptError # # the path that failed to load diff --git a/core/exception.rbs b/core/exception.rbs index c1894e647..d428d48ab 100644 --- a/core/exception.rbs +++ b/core/exception.rbs @@ -19,7 +19,7 @@ # # * NoMemoryError # * ScriptError -# * [LoadError](https://docs.ruby-lang.org/en/master/LoadError.html) +# * LoadError # * NotImplementedError # * SyntaxError # * SecurityError @@ -51,7 +51,7 @@ # * ZeroDivisionError # * SystemExit # * SystemStackError -# * [fatal](https://docs.ruby-lang.org/en/master/fatal.html) +# * [fatal](rdoc-ref:fatal) # class Exception # -# FNM_CASEFOLD # [File::FNM_CASEFOLD](rdoc-ref:File::Constants@File-3A-3AFNM_CASEFOLD) # File::Constants::FNM_CASEFOLD: Integer # -# FNM_DOTMATCH # [File::FNM_DOTMATCH](rdoc-ref:File::Constants@File-3A-3AFNM_DOTMATCH) # File::Constants::FNM_DOTMATCH: Integer # -# FNM_EXTGLOB # [File::FNM_EXTGLOB](rdoc-ref:File::Constants@File-3A-3AFNM_EXTGLOB) # File::Constants::FNM_EXTGLOB: Integer # -# FNM_NOESCAPE # [File::FNM_NOESCAPE](rdoc-ref:File::Constants@File-3A-3AFNM_NOESCAPE) # File::Constants::FNM_NOESCAPE: Integer # -# FNM_PATHNAME # [File::FNM_PATHNAME](rdoc-ref:File::Constants@File-3A-3AFNM_PATHNAME) # File::Constants::FNM_PATHNAME: Integer # -# FNM_SHORTNAME # [File::FNM_SHORTNAME](rdoc-ref:File::Constants@File-3A-3AFNM_SHORTNAME) # File::Constants::FNM_SHORTNAME: Integer # -# FNM_SYSCASE # [File::FNM_SYSCASE](rdoc-ref:File::Constants@File-3A-3AFNM_SYSCASE) # File::Constants::FNM_SYSCASE: Integer diff --git a/core/gc.rbs b/core/gc.rbs index 4177e2cab..f69551561 100644 --- a/core/gc.rbs +++ b/core/gc.rbs @@ -167,7 +167,8 @@ module GC # Configuration parameters are GC implementation-specific and may change without # notice. # - # This method can be called without parameters to retrieve the current config. + # This method can be called without parameters to retrieve the current config as + # a `Hash` with `Symbol` keys. # # This method can also be called with a `Hash` argument to assign values to # valid config keys. Config keys missing from the passed `Hash` will be left @@ -185,7 +186,24 @@ module GC # # This method is only expected to work on CRuby. # - # Valid config keys for Ruby's default GC implementation are: + # ### GC Implementation independent values + # + # The `GC.config` hash can also contain keys that are global and read-only. + # These keys are not specific to any one GC library implementation and + # attempting to write to them will raise `ArgumentError`. + # + # There is currently only one global, read-only key: + # + # implementation + # : Returns a `String` containing the name of the currently loaded GC library, + # if one has been loaded using `RUBY_GC_LIBRARY`, and "default" in all other + # cases + # + # + # ### GC Implementation specific values + # + # GC libraries are expected to document their own configuration. Valid keys for + # Ruby's default GC implementation are: # # rgengc_allow_full_mark # : Controls whether the GC is allowed to run a full mark (young & old diff --git a/core/hash.rbs b/core/hash.rbs index 6d7fb7033..10fe0e0cb 100644 --- a/core/hash.rbs +++ b/core/hash.rbs @@ -1226,7 +1226,7 @@ class Hash[unchecked out K, unchecked out V] < Object # Returns a new String containing the hash entries: # # h = {foo: 0, bar: 1, baz: 2} - # h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}" + # h.inspect # => "{foo: 0, bar: 1, baz: 2}" # def inspect: () -> String @@ -1628,7 +1628,7 @@ class Hash[unchecked out K, unchecked out V] < Object # Returns a new String containing the hash entries: # # h = {foo: 0, bar: 1, baz: 2} - # h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}" + # h.inspect # => "{foo: 0, bar: 1, baz: 2}" # alias to_s inspect diff --git a/core/kernel.rbs b/core/kernel.rbs index 04487f19b..765dc3f34 100644 --- a/core/kernel.rbs +++ b/core/kernel.rbs @@ -675,7 +675,7 @@ module Kernel : BasicObject # # String([0, 1, 2]) # => "[0, 1, 2]" # String(0..5) # => "0..5" - # String({foo: 0, bar: 1}) # => "{:foo=>0, :bar=>1}" + # String({foo: 0, bar: 1}) # => "{foo: 0, bar: 1}" # # Raises `TypeError` if `object` cannot be converted to a string. # diff --git a/core/nil_class.rbs b/core/nil_class.rbs index d93514d07..11d78947e 100644 --- a/core/nil_class.rbs +++ b/core/nil_class.rbs @@ -18,6 +18,9 @@ # * #to_r # * #to_s # +# While `nil` doesn't have an explicitly defined #to_hash method, it can be used +# in `**` unpacking, not adding any keyword arguments. +# # Another method provides inspection: # # * #inspect diff --git a/core/numeric.rbs b/core/numeric.rbs index 3cc0fd685..3cba27149 100644 --- a/core/numeric.rbs +++ b/core/numeric.rbs @@ -776,7 +776,7 @@ class Numeric # Rational(1, 2).to_int # => 0 # Rational(2, 1).to_int # => 2 # Complex(2, 0).to_int # => 2 - # Complex(2, 1) # Raises RangeError (non-zero imaginary part) + # Complex(2, 1).to_int # Raises RangeError (non-zero imaginary part) # def to_int: () -> Integer diff --git a/core/proc.rbs b/core/proc.rbs index 6507bbfd9..6bbd7e909 100644 --- a/core/proc.rbs +++ b/core/proc.rbs @@ -236,19 +236,86 @@ # Since `return` and `break` exits the block itself in lambdas, lambdas cannot # be orphaned. # -# ## Numbered parameters +# ## Anonymous block parameters # -# Numbered parameters are implicitly defined block parameters intended to -# simplify writing short blocks: +# To simplify writing short blocks, Ruby provides two different types of +# anonymous parameters: `it` (single parameter) and numbered ones: `_1`, `_2` +# and so on. # # # Explicit parameter: # %w[test me please].each { |str| puts str.upcase } # prints TEST, ME, PLEASE # (1..5).map { |i| i**2 } # => [1, 4, 9, 16, 25] # -# # Implicit parameter: +# # it: +# %w[test me please].each { puts it.upcase } # prints TEST, ME, PLEASE +# (1..5).map { it**2 } # => [1, 4, 9, 16, 25] +# +# # Numbered parameter: # %w[test me please].each { puts _1.upcase } # prints TEST, ME, PLEASE # (1..5).map { _1**2 } # => [1, 4, 9, 16, 25] # +# ### `it` +# +# `it` is a name that is available inside a block when no explicit parameters +# defined, as shown above. +# +# %w[test me please].each { puts it.upcase } # prints TEST, ME, PLEASE +# (1..5).map { it**2 } # => [1, 4, 9, 16, 25] +# +# `it` is a "soft keyword": it is not a reserved name, and can be used as a name +# for methods and local variables: +# +# it = 5 # no warnings +# def it(&block) # RSpec-like API, no warnings +# # ... +# end +# +# `it` can be used as a local variable even in blocks that use it as an implicit +# parameter (though this style is obviously confusing): +# +# [1, 2, 3].each { +# # takes a value of implicit parameter "it" and uses it to +# # define a local variable with the same name +# it = it**2 +# p it +# } +# +# In a block with explicit parameters defined `it` usage raises an exception: +# +# [1, 2, 3].each { |x| p it } +# # syntax error found (SyntaxError) +# # [1, 2, 3].each { |x| p it } +# # ^~ `it` is not allowed when an ordinary parameter is defined +# +# But if a local name (variable or method) is available, it would be used: +# +# it = 5 +# [1, 2, 3].each { |x| p it } +# # Prints 5, 5, 5 +# +# Blocks using `it` can be nested: +# +# %w[test me].each { it.each_char { p it } } +# # Prints "t", "e", "s", "t", "m", "e" +# +# Blocks using `it` are considered to have one parameter: +# +# p = proc { it**2 } +# l = lambda { it**2 } +# p.parameters # => [[:opt, nil]] +# p.arity # => 1 +# l.parameters # => [[:req]] +# l.arity # => 1 +# +# ### Numbered parameters +# +# Numbered parameters are another way to name block parameters implicitly. +# Unlike `it`, numbered parameters allow to refer to several parameters in one +# block. +# +# %w[test me please].each { puts _1.upcase } # prints TEST, ME, PLEASE +# {a: 100, b: 200}.map { "#{_1} = #{_2}" } # => "a = 100", "b = 200" +# # Parameter names from `_1` to `_9` are supported: # # [10, 20, 30].zip([40, 50, 60], [70, 80, 90]).map { _1 + _2 + _3 } @@ -262,11 +329,16 @@ # [10, 20, 30].map { |x| _1**2 } # # SyntaxError (ordinary parameter is defined) # +# Numbered parameters can't be mixed with `it` either: +# +# [10, 20, 30].map { _1 + it } +# # SyntaxError: `it` is not allowed when a numbered parameter is already used +# # To avoid conflicts, naming local variables or method arguments `_1`, `_2` and -# so on, causes a warning. +# so on, causes an error. # -# _1 = 'test' -# # warning: `_1' is reserved as numbered parameter +# _1 = 'test' +# # ^~ _1 is reserved for numbered parameters (SyntaxError) # # Using implicit numbered parameters affects block's arity: # @@ -280,12 +352,10 @@ # Blocks with numbered parameters can't be nested: # # %w[test me].each { _1.each_char { p _1 } } -# # SyntaxError (numbered parameter is already used in outer block here) +# # numbered parameter is already used in outer block (SyntaxError) # # %w[test me].each { _1.each_char { p _1 } } # # ^~ # -# Numbered parameters were introduced in Ruby 2.7. -# class Proc interface _Callable def call: (?) -> untyped diff --git a/core/regexp.rbs b/core/regexp.rbs index 108942a9e..f713b907d 100644 --- a/core/regexp.rbs +++ b/core/regexp.rbs @@ -897,7 +897,7 @@ # * [Nl, Letter_Number](https://www.compart.com/en/unicode/category/Nl). # * [No, Other_Number](https://www.compart.com/en/unicode/category/No). # -# Punctation: +# Punctuation: # # * `P`, `Punctuation`: `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`. # * [Pc, @@ -1603,7 +1603,7 @@ class Regexp # `self`: # # * Is a regexp literal; see [Regexp - # Literals](rdoc-ref:literals.rdoc@Regexp+Literals). + # Literals](rdoc-ref:syntax/literals.rdoc@Regexp+Literals). # * Does not contain interpolations; see [Regexp # interpolation](rdoc-ref:Regexp@Interpolation+Mode). # * Is at the left of the expression. diff --git a/core/ruby_vm.rbs b/core/ruby_vm.rbs index 1b8d75e3a..db629d3ab 100644 --- a/core/ruby_vm.rbs +++ b/core/ruby_vm.rbs @@ -591,7 +591,7 @@ module RubyVM::AbstractSyntaxTree # # RubyVM::AbstractSyntaxTree::Location instances are created by - # RubyVM::AbstractSyntaxTree#locations. + # RubyVM::AbstractSyntaxTree::Node#locations. # # This class is MRI specific. # diff --git a/core/rubygems/errors.rbs b/core/rubygems/errors.rbs index 19b87dbf5..986a0b904 100644 --- a/core/rubygems/errors.rbs +++ b/core/rubygems/errors.rbs @@ -83,7 +83,9 @@ # # ## License # -# See [LICENSE.txt](rdoc-ref:lib/rubygems/LICENSE.txt) for permissions. +# See +# [LICENSE.txt](https://github.com/rubygems/rubygems/blob/master/LICENSE.txt) +# for permissions. # # Thanks! # diff --git a/core/rubygems/rubygems.rbs b/core/rubygems/rubygems.rbs index 7364b941b..8b87aa6ce 100644 --- a/core/rubygems/rubygems.rbs +++ b/core/rubygems/rubygems.rbs @@ -83,7 +83,9 @@ # # ## License # -# See [LICENSE.txt](rdoc-ref:lib/rubygems/LICENSE.txt) for permissions. +# See +# [LICENSE.txt](https://github.com/rubygems/rubygems/blob/master/LICENSE.txt) +# for permissions. # # Thanks! # diff --git a/core/string.rbs b/core/string.rbs index 1df3330e8..ab81267a6 100644 --- a/core/string.rbs +++ b/core/string.rbs @@ -16,12 +16,12 @@ # * Method #String. # # Some `String` methods modify `self`. Typically, a method whose name ends with -# `!` modifies `self` and returns `self`; often a similarly named method +# `!` modifies `self` and returns `self`; often, a similarly named method # (without the `!`) returns a new string. # -# In general, if there exist both bang and non-bang version of method, the bang! -# mutates and the non-bang! does not. However, a method without a bang can also -# mutate, such as String#replace. +# In general, if both bang and non-bang versions of a method exist, the bang +# method mutates and the non-bang method does not. However, a method without a +# bang can also mutate, such as String#replace. # # ## Substitution Methods # @@ -36,59 +36,58 @@ # # Each of these methods takes: # -# * A first argument, `pattern` (string or regexp), that specifies the +# * A first argument, `pattern` (String or Regexp), that specifies the # substring(s) to be replaced. # -# * Either of these: +# * Either of the following: # -# * A second argument, `replacement` (string or hash), that determines the +# * A second argument, `replacement` (String or Hash), that determines the # replacing string. # * A block that will determine the replacing string. # -# The examples in this section mostly use methods String#sub and String#gsub; -# the principles illustrated apply to all four substitution methods. +# The examples in this section mostly use the String#sub and String#gsub +# methods; the principles illustrated apply to all four substitution methods. # # **Argument `pattern`** # # Argument `pattern` is commonly a regular expression: # # s = 'hello' -# s.sub(/[aeiou]/, '*')# => "h*llo" +# s.sub(/[aeiou]/, '*') # => "h*llo" # s.gsub(/[aeiou]/, '*') # => "h*ll*" -# s.gsub(/[aeiou]/, '')# => "hll" -# s.sub(/ell/, 'al') # => "halo" -# s.gsub(/xyzzy/, '*') # => "hello" +# s.gsub(/[aeiou]/, '') # => "hll" +# s.sub(/ell/, 'al') # => "halo" +# s.gsub(/xyzzy/, '*') # => "hello" # 'THX1138'.gsub(/\d+/, '00') # => "THX00" # # When `pattern` is a string, all its characters are treated as ordinary -# characters (not as regexp special characters): +# characters (not as Regexp special characters): # # 'THX1138'.gsub('\d+', '00') # => "THX1138" # # **`String` `replacement`** # -# If `replacement` is a string, that string will determine the replacing string -# that is to be substituted for the matched text. +# If `replacement` is a string, that string determines the replacing string that +# is substituted for the matched text. # # Each of the examples above uses a simple string as the replacing string. # # `String` `replacement` may contain back-references to the pattern's captures: # -# * `\n` (*n* a non-negative integer) refers to `$n`. +# * `\n` (*n* is a non-negative integer) refers to `$n`. # * `\k` refers to the named capture `name`. # # See Regexp for details. # # Note that within the string `replacement`, a character combination such as -# `$&` is treated as ordinary text, and not as a special match variable. -# However, you may refer to some special match variables using these -# combinations: +# `$&` is treated as ordinary text, not as a special match variable. However, +# you may refer to some special match variables using these combinations: # # * `\&` and `\0` correspond to `$&`, which contains the complete matched # text. -# * `\'` corresponds to `$'`, which contains string after match. -# * `\`` corresponds to `$``, which contains string before match. -# * `\+` corresponds to `$+`, which contains last capture group. +# * `\'` corresponds to `$'`, which contains the string after the match. +# * `\`` corresponds to `$``, which contains the string before the match. +# * `\+` corresponds to `$+`, which contains the last capture group. # # See Regexp for details. # @@ -103,16 +102,16 @@ # double-quoted string literal, you need to write `"..\\\\&.."`. # # If you want to write a non-back-reference string `\&` in `replacement`, you -# need first to escape the backslash to prevent this method from interpreting it +# need to first escape the backslash to prevent this method from interpreting it # as a back-reference, and then you need to escape the backslashes again to # prevent a string literal from consuming them: `"..\\\\\\\\&.."`. # -# You may want to use the block form to avoid a lot of backslashes. +# You may want to use the block form to avoid excessive backslashes. # # **\Hash `replacement`** # -# If argument `replacement` is a hash, and `pattern` matches one of its keys, -# the replacing string is the value for that key: +# If the argument `replacement` is a hash, and `pattern` matches one of its +# keys, the replacing string is the value for that key: # # h = {'foo' => 'bar', 'baz' => 'bat'} # 'food'.sub('foo', h) # => "bard" @@ -127,15 +126,15 @@ # In the block form, the current match string is passed to the block; the # block's return value becomes the replacing string: # -# s = '@' -# '1234'.gsub(/\d/) {|match| s.succ! } # => "ABCD" +# s = '@' +# '1234'.gsub(/\d/) { |match| s.succ! } # => "ABCD" # # Special match variables such as `$1`, `$2`, `$``, `$&`, and `$'` are set # appropriately. # # ## Whitespace in Strings # -# In class `String`, *whitespace* is defined as a contiguous sequence of +# In the class `String`, *whitespace* is defined as a contiguous sequence of # characters consisting of any mixture of the following: # # * NL (null): `"\x00"`, `"\u0000"`. @@ -146,50 +145,51 @@ # * CR (carriage return): `"\x0d"`, `"\r"`. # * SP (space): `"\x20"`, `" "`. # -# Whitespace is relevant for these methods: +# Whitespace is relevant for the following methods: # -# * #lstrip, #lstrip!: strip leading whitespace. -# * #rstrip, #rstrip!: strip trailing whitespace. -# * #strip, #strip!: strip leading and trailing whitespace. +# * #lstrip, #lstrip!: Strip leading whitespace. +# * #rstrip, #rstrip!: Strip trailing whitespace. +# * #strip, #strip!: Strip leading and trailing whitespace. # # ## `String` Slices # -# A *slice* of a string is a substring that is selected by certain criteria. +# A *slice* of a string is a substring selected by certain criteria. # -# These instance methods make use of slicing: +# These instance methods utilize slicing: # -# * String#[] (aliased as String#slice): returns a slice copied from `self`. -# * String#[]=: returns a copy of `self` with a slice replaced. -# * String#slice!: returns `self` with a slice removed. +# * String#[] (aliased as String#slice): Returns a slice copied from `self`. +# * String#[]=: Mutates `self` with the slice replaced. +# * String#slice!: Mutates `self` with the slice removed and returns the +# removed slice. # # Each of the above methods takes arguments that determine the slice to be # copied or replaced. # -# The arguments have several forms. For string `string`, the forms are: +# The arguments have several forms. For a string `string`, the forms are: # -# * `string[index]`. -# * `string[start, length]`. -# * `string[range]`. -# * `string[regexp, capture = 0]`. -# * `string[substring]`. +# * `string[index]` +# * `string[start, length]` +# * `string[range]` +# * `string[regexp, capture = 0]` +# * `string[substring]` # # **`string[index]`** # -# When non-negative integer argument `index` is given, the slice is the +# When a non-negative integer argument `index` is given, the slice is the # 1-character substring found in `self` at character offset `index`: # -# 'bar'[0] # => "b" -# 'bar'[2] # => "r" -# 'bar'[20] # => nil -# 'тест'[2] # => "с" -# 'こんにちは'[4] # => "は" +# 'bar'[0] # => "b" +# 'bar'[2] # => "r" +# 'bar'[20] # => nil +# 'тест'[2] # => "с" +# 'こんにちは'[4] # => "は" # -# When negative integer `index` is given, the slice begins at the offset given +# When a negative integer `index` is given, the slice begins at the offset given # by counting backward from the end of `self`: # -# 'bar'[-3] # => "b" -# 'bar'[-1] # => "r" -# 'bar'[-20] # => nil +# 'bar'[-3] # => "b" +# 'bar'[-1] # => "r" +# 'bar'[-20] # => nil # # **`string[start, length]`** # @@ -197,92 +197,92 @@ # begins at character offset `start`, if it exists, and continues for `length` # characters, if available: # -# 'foo'[0, 2] # => "fo" -# 'тест'[1, 2] # => "ес" -# 'こんにちは'[2, 2] # => "にち" +# 'foo'[0, 2] # => "fo" +# 'тест'[1, 2] # => "ес" +# 'こんにちは'[2, 2] # => "にち" # # Zero length. -# 'foo'[2, 0] # => "" +# 'foo'[2, 0] # => "" # # Length not entirely available. -# 'foo'[1, 200] # => "oo" +# 'foo'[1, 200] # => "oo" # # Start out of range. # 'foo'[4, 2] # => nil # -# Special case: if `start` is equal to the length of `self`, the slice is a new -# empty string: +# Special case: if `start` equals the length of `self`, the slice is a new empty +# string: # -# 'foo'[3, 2] # => "" -# 'foo'[3, 200] # => "" +# 'foo'[3, 2] # => "" +# 'foo'[3, 200] # => "" # -# When negative `start` and non-negative `length` are given, the slice beginning -# is determined by counting backward from the end of `self`, and the slice -# continues for `length` characters, if available: +# When a negative `start` and non-negative `length` are given, the slice begins +# by counting backward from the end of `self`, and continues for `length` +# characters, if available: # -# 'foo'[-2, 2] # => "oo" -# 'foo'[-2, 200] # => "oo" +# 'foo'[-2, 2] # => "oo" +# 'foo'[-2, 200] # => "oo" # # Start out of range. # 'foo'[-4, 2] # => nil # -# When negative `length` is given, there is no slice: +# When a negative `length` is given, there is no slice: # -# 'foo'[1, -1] # => nil -# 'foo'[-2, -1] # => nil +# 'foo'[1, -1] # => nil +# 'foo'[-2, -1] # => nil # # **`string[range]`** # -# When Range argument `range` is given, creates a substring of `string` using -# the indices in `range`. The slice is then determined as above: +# When a Range argument `range` is given, it creates a substring of `string` +# using the indices in `range`. The slice is then determined as above: # -# 'foo'[0..1] # => "fo" -# 'foo'[0, 2] # => "fo" +# 'foo'[0..1] # => "fo" +# 'foo'[0, 2] # => "fo" # -# 'foo'[2...2] # => "" -# 'foo'[2, 0] # => "" +# 'foo'[2...2] # => "" +# 'foo'[2, 0] # => "" # -# 'foo'[1..200] # => "oo" -# 'foo'[1, 200] # => "oo" +# 'foo'[1..200] # => "oo" +# 'foo'[1, 200] # => "oo" # -# 'foo'[4..5] # => nil -# 'foo'[4, 2] # => nil +# 'foo'[4..5] # => nil +# 'foo'[4, 2] # => nil # -# 'foo'[-4..-3] # => nil -# 'foo'[-4, 2] # => nil +# 'foo'[-4..-3] # => nil +# 'foo'[-4, 2] # => nil # -# 'foo'[3..4] # => "" -# 'foo'[3, 2] # => "" +# 'foo'[3..4] # => "" +# 'foo'[3, 2] # => "" # -# 'foo'[-2..-1] # => "oo" -# 'foo'[-2, 2] # => "oo" +# 'foo'[-2..-1] # => "oo" +# 'foo'[-2, 2] # => "oo" # -# 'foo'[-2..197] # => "oo" -# 'foo'[-2, 200] # => "oo" +# 'foo'[-2..197] # => "oo" +# 'foo'[-2, 200] # => "oo" # # **`string[regexp, capture = 0]`** # # When the Regexp argument `regexp` is given, and the `capture` argument is `0`, # the slice is the first matching substring found in `self`: # -# 'foo'[/o/] # => "o" -# 'foo'[/x/] # => nil +# 'foo'[/o/] # => "o" +# 'foo'[/x/] # => nil # s = 'hello there' -# s[/[aeiou](.)\1/] # => "ell" -# s[/[aeiou](.)\1/, 0] # => "ell" +# s[/[aeiou](.)\1/] # => "ell" +# s[/[aeiou](.)\1/, 0] # => "ell" # -# If argument `capture` is given and not `0`, it should be either an capture -# group index (integer) or a capture group name (string or symbol); the slice is -# the specified capture (see Regexp@Groups+and+Captures): +# If the argument `capture` is provided and not `0`, it should be either a +# capture group index (integer) or a capture group name (String or Symbol); the +# slice is the specified capture (see Regexp@Groups and Captures): # # s = 'hello there' # s[/[aeiou](.)\1/, 1] # => "l" # s[/(?[aeiou])(?[^aeiou])/, "non_vowel"] # => "l" -# s[/(?[aeiou])(?[^aeiou])/, :vowel] # => "e" +# s[/(?[aeiou])(?[^aeiou])/, :vowel] # => "e" # # If an invalid capture group index is given, there is no slice. If an invalid # capture group name is given, `IndexError` is raised. # # **`string[substring]`** # -# When the single `String` argument `substring` is given, returns the substring -# from `self` if found, otherwise `nil`: +# When the single `String` argument `substring` is given, it returns the +# substring from `self` if found, otherwise `nil`: # # 'foo'['oo'] # => "oo" # 'foo'['xx'] # => nil @@ -291,8 +291,8 @@ # # First, what's elsewhere. Class `String`: # -# * Inherits from [class Object](rdoc-ref:Object@What-27s+Here). -# * Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here). +# * Inherits from the [Object class](rdoc-ref:Object@What-27s+Here). +# * Includes the [Comparable module](rdoc-ref:Comparable@What-27s+Here). # # Here, class `String` provides methods that are useful for: # @@ -315,11 +315,11 @@ # # ### Methods for a Frozen/Unfrozen String # -# * #+@: Returns a string that is not frozen: `self`, if not frozen; -# `self.dup` otherwise. -# * #-@ (aliased as #dedup): Returns a string that is frozen: `self`, if +# * #+@: Returns a string that is not frozen: `self` if not frozen; `self.dup` +# otherwise. +# * #-@ (aliased as #dedup): Returns a string that is frozen: `self` if # already frozen; `self.freeze` otherwise. -# * #freeze: Freezes `self`, if not already frozen; returns `self`. +# * #freeze: Freezes `self` if not already frozen; returns `self`. # # ### Methods for Querying # @@ -384,7 +384,8 @@ # # *Insertion* # -# * #insert: Returns `self` with a given string inserted at a given offset. +# * #insert: Returns `self` with a given string inserted at a specified +# offset. # * #<<: Returns `self` concatenated with a given string or integer. # * #append_as_bytes: Returns `self` concatenated with strings without # performing any encoding validation or conversion. @@ -421,8 +422,8 @@ # # *Encoding* # -# * #encode!: Returns `self` with all characters transcoded from one given -# encoding into another. +# * #encode!: Returns `self` with all characters transcoded from one encoding +# to another. # * #unicode_normalize!: Unicode-normalizes `self`; returns `self`. # * #scrub!: Replaces each invalid byte with a given character; returns # `self`. @@ -442,8 +443,8 @@ # `nil` otherwise. # * #strip!: Removes leading and trailing whitespace; returns `self` if any # changes, `nil` otherwise. -# * #chomp!: Removes trailing record separator, if found; returns `self` if -# any changes, `nil` otherwise. +# * #chomp!: Removes the trailing record separator, if found; returns `self` +# if any changes, `nil` otherwise. # * #chop!: Removes trailing newline characters if found; otherwise removes # the last character; returns `self` if any changes, `nil` otherwise. # @@ -454,9 +455,9 @@ # # *Extension* # -# * #*: Returns the concatenation of multiple copies of `self`, +# * #*: Returns the concatenation of multiple copies of `self`. # * #+: Returns the concatenation of `self` and a given other string. -# * #center: Returns a copy of `self` centered between pad substring. +# * #center: Returns a copy of `self` centered between pad substrings. # * #concat: Returns the concatenation of `self` with given other strings. # * #prepend: Returns the concatenation of a given other string with `self`. # * #ljust: Returns a copy of `self` of a given length, right-padded with a @@ -472,28 +473,28 @@ # * #unicode_normalize: Returns a copy of `self` with each character # Unicode-normalized. # * #encode: Returns a copy of `self` with all characters transcoded from one -# given encoding into another. +# encoding to another. # # *Substitution* # # * #dump: Returns a copy of `self` with all non-printing characters replaced # by xHH notation and all special characters escaped. -# * #undump: Returns a copy of `self` with all `\xNN` notation replace by -# `\uNNNN` notation and all escaped characters unescaped. +# * #undump: Returns a copy of `self` with all `\xNN` notations replaced by +# `\uNNNN` notations and all escaped characters unescaped. # * #sub: Returns a copy of `self` with the first substring matching a given -# pattern replaced with a given replacement string;. +# pattern replaced with a given replacement string. # * #gsub: Returns a copy of `self` with each substring that matches a given # pattern replaced with a given replacement string. # * #succ (aliased as #next): Returns the string that is the successor to # `self`. # * #reverse: Returns a copy of `self` with its characters in reverse order. # * #tr: Returns a copy of `self` with specified characters replaced with -# specified replacement characters. +# specified replacement characters. # * #tr_s: Returns a copy of `self` with specified characters replaced with # specified replacement characters, removing duplicates from the substrings # that were modified. # * #%: Returns the string resulting from formatting a given object into -# `self` +# `self`. # # *Casing* # @@ -506,7 +507,7 @@ # # *Deletion* # -# * #delete: Returns a copy of `self` with characters removed +# * #delete: Returns a copy of `self` with characters removed. # * #delete_prefix: Returns a copy of `self` with a given prefix removed. # * #delete_suffix: Returns a copy of `self` with a given suffix removed. # * #lstrip: Returns a copy of `self` with leading whitespace removed. @@ -520,7 +521,7 @@ # * #squeeze: Returns a copy of `self` with contiguous duplicate characters # removed. # * #[] (aliased as #slice): Returns a substring determined by a given index, -# start/length, or range, or string. +# start/length, range, regexp, or string. # * #byteslice: Returns a substring determined by a given index, start/length, # or range. # * #chr: Returns the first character. @@ -539,7 +540,7 @@ # * #bytes: Returns an array of the bytes in `self`. # * #chars: Returns an array of the characters in `self`. # * #codepoints: Returns an array of the integer ordinals in `self`. -# * #getbyte: Returns an integer byte as determined by a given index. +# * #getbyte: Returns the integer byte at the given index in `self`. # * #grapheme_clusters: Returns an array of the grapheme clusters in `self`. # # *Splitting* @@ -547,17 +548,17 @@ # * #lines: Returns an array of the lines in `self`, as determined by a given # record separator. # * #partition: Returns a 3-element array determined by the first substring -# that matches a given substring or regexp, +# that matches a given substring or regexp. # * #rpartition: Returns a 3-element array determined by the last substring -# that matches a given substring or regexp, +# that matches a given substring or regexp. # * #split: Returns an array of substrings determined by a given delimiter -- -# regexp or string -- or, if a block given, passes those substrings to the -# block. +# regexp or string -- or, if a block is given, passes those substrings to +# the block. # # *Matching* # # * #scan: Returns an array of substrings matching a given regexp or string, -# or, if a block given, passes each matching substring to the block. +# or, if a block is given, passes each matching substring to the block. # * #unpack: Returns an array of substrings extracted from `self` according to # a given format. # * #unpack1: Returns the first substring extracted from `self` according to a @@ -577,8 +578,8 @@ # # *Strings and Symbols* # -# * #inspect: Returns copy of `self`, enclosed in double-quotes, with special -# characters escaped. +# * #inspect: Returns a copy of `self`, enclosed in double quotes, with +# special characters escaped. # * #intern (aliased as #to_sym): Returns the symbol corresponding to `self`. # # ### Methods for Iterating @@ -734,7 +735,8 @@ class String # rdoc-file=string.c # - +string -> new_string or self # --> - # Returns `self` if `self` is not frozen. + # Returns `self` if `self` is not frozen and can be mutated without warning + # issuance. # # Otherwise returns `self.dup`, which is not frozen. # diff --git a/core/time.rbs b/core/time.rbs index 9c036d7e2..0f8c3989e 100644 --- a/core/time.rbs +++ b/core/time.rbs @@ -331,6 +331,10 @@ # keyword argument `in:`, and when Time#getlocal or Time#localtime is called # with `tz` as the value for positional argument `zone`. # +# The UTC offset will be calculated as the difference between the original +# time and the returned object as an `Integer`. If the object is in fixed +# offset, its `utc_offset` is also counted. +# # Argument # : a [Time-like object](rdoc-ref:Time@Time-Like+Objects). # diff --git a/core/trace_point.rbs b/core/trace_point.rbs index cb7efcbe5..473200105 100644 --- a/core/trace_point.rbs +++ b/core/trace_point.rbs @@ -1,123 +1,121 @@ # -# A class that provides the functionality of Kernel#set_trace_func in a nice -# Object-Oriented API. +# A class that provides the functionality of Kernel#set_trace_func in a +# well-structured Object-Oriented API. # # ## Example # -# We can use TracePoint to gather information specifically for exceptions: +# Use TracePoint to gather information specifically for exceptions: # # trace = TracePoint.new(:raise) do |tp| -# p [tp.lineno, tp.event, tp.raised_exception] +# p [tp.lineno, tp.event, tp.raised_exception] # end # #=> # # -# trace.enable -# #=> false +# trace.enable #=> false # # 0 / 0 # #=> [5, :raise, #] # # ## Events # -# If you don't specify the type of events you want to listen for, TracePoint +# If you don't specify the types of events you want to listen for, TracePoint # will include all available events. # -# **Note** do not depend on current event set, as this list is subject to -# change. Instead, it is recommended you specify the type of events you want to +# **Note:** Do not depend on the current event set, as this list is subject to +# change. Instead, it is recommended to specify the types of events you want to # use. # # To filter what is traced, you can pass any of the following as `events`: # # `:line` -# : execute an expression or statement on a new line +# : Execute an expression or statement on a new line. # # `:class` -# : start a class or module definition +# : Start a class or module definition. # # `:end` -# : finish a class or module definition +# : Finish a class or module definition. # # `:call` -# : call a Ruby method +# : Call a Ruby method. # # `:return` -# : return from a Ruby method +# : Return from a Ruby method. # # `:c_call` -# : call a C-language routine +# : Call a C-language routine. # # `:c_return` -# : return from a C-language routine +# : Return from a C-language routine. # # `:raise` -# : raise an exception +# : Raise an exception. # # `:rescue` -# : rescue an exception +# : Rescue an exception. # # `:b_call` -# : event hook at block entry +# : Event hook at block entry. # # `:b_return` -# : event hook at block ending +# : Event hook at block ending. # # `:a_call` -# : event hook at all calls (`call`, `b_call`, and `c_call`) +# : Event hook at all calls (`call`, `b_call`, and `c_call`). # # `:a_return` -# : event hook at all returns (`return`, `b_return`, and `c_return`) +# : Event hook at all returns (`return`, `b_return`, and `c_return`). # # `:thread_begin` -# : event hook at thread beginning +# : Event hook at thread beginning. # # `:thread_end` -# : event hook at thread ending +# : Event hook at thread ending. # # `:fiber_switch` -# : event hook at fiber switch +# : Event hook at fiber switch. # # `:script_compiled` -# : new Ruby code compiled (with `eval`, `load` or `require`) +# : New Ruby code compiled (with `eval`, `load`, or `require`). # class TracePoint # # Returns a new TracePoint object, not enabled by default. # - # Next, in order to activate the trace, you must use TracePoint#enable + # To activate the TracePoint object, use TracePoint#enable: # # trace = TracePoint.new(:call) do |tp| - # p [tp.lineno, tp.defined_class, tp.method_id, tp.event] + # p [tp.lineno, tp.defined_class, tp.method_id, tp.event] # end # #=> # # - # trace.enable - # #=> false + # trace.enable #=> false # # puts "Hello, TracePoint!" # # ... # # [48, IRB::Notifier::AbstractNotifier, :printf, :call] # # ... # - # When you want to deactivate the trace, you must use TracePoint#disable + # To deactivate the trace, use TracePoint#disable. # # trace.disable # # See TracePoint@Events for possible events and more information. # - # A block must be given, otherwise an ArgumentError is raised. + # A block must be given; otherwise, an ArgumentError is raised. # # If the trace method isn't included in the given events filter, a RuntimeError # is raised. # # TracePoint.trace(:line) do |tp| - # p tp.raised_exception + # p tp.raised_exception # end # #=> RuntimeError: 'raised_exception' not supported by this event # - # If the trace method is called outside block, a RuntimeError is raised. + # If the trace method is called outside a block, a RuntimeError is raised. # # TracePoint.trace(:line) do |tp| # $tp = tp @@ -132,13 +130,12 @@ class TracePoint # rdoc-file=trace_point.rb # - TracePoint.allow_reentry { block } # --> - # In general, while a TracePoint callback is running, other registered callbacks - # are not called to avoid confusion by reentrance. This method allows the - # reentrance in a given block. This method should be used carefully, otherwise - # the callback can be easily called infinitely. + # Generally, while a TracePoint callback is running, other registered callbacks + # are not called to avoid confusion from reentrance. This method allows + # reentrance within a given block. Use this method carefully to avoid infinite + # callback invocation. # - # If this method is called when the reentrance is already allowed, it raises a - # RuntimeError. + # If called when reentrance is already allowed, it raises a RuntimeError. # # **Example:** # @@ -146,7 +143,7 @@ class TracePoint # # --------------- # # line_handler = TracePoint.new(:line) do |tp| - # next if tp.path != __FILE__ # only work in this file + # next if tp.path != __FILE__ # Only works in this file # puts "Line handler" # binding.eval("class C; end") # end.enable @@ -158,15 +155,15 @@ class TracePoint # class B # end # - # # This script will print "Class handler" only once: when inside :line - # # handler, all other handlers are ignored + # # This script will print "Class handler" only once: when inside the :line + # # handler, all other handlers are ignored. # # # With reentry # # ------------ # # line_handler = TracePoint.new(:line) do |tp| - # next if tp.path != __FILE__ # only work in this file - # next if (__LINE__..__LINE__+3).cover?(tp.lineno) # don't be invoked from itself + # next if tp.path != __FILE__ # Only works in this file + # next if (__LINE__..__LINE__+3).cover?(tp.lineno) # Prevent infinite calls # puts "Line handler" # TracePoint.allow_reentry { binding.eval("class C; end") } # end.enable @@ -178,15 +175,15 @@ class TracePoint # class B # end # - # # This wil print "Class handler" twice: inside allow_reentry block in :line + # # This will print "Class handler" twice: inside the allow_reentry block in the :line # # handler, other handlers are enabled. # # Note that the example shows the principal effect of the method, but its # practical usage is for debugging libraries that sometimes require other - # libraries hooks to not be affected by debugger being inside trace point + # libraries' hooks to not be affected by the debugger being inside trace point # handling. Precautions should be taken against infinite recursion in this case - # (note that we needed to filter out calls by itself from :line handler, - # otherwise it will call itself infinitely). + # (note that we needed to filter out calls by itself from the :line handler, + # otherwise it would call itself infinitely). # def self.allow_reentry: [T] () { (nil) -> T } -> T @@ -196,8 +193,8 @@ class TracePoint # --> # Returns internal information of TracePoint. # - # The contents of the returned value are implementation specific. It may be - # changed in future. + # The contents of the returned value are implementation-specific and may change + # in the future. # # This method is only for debugging TracePoint itself. # @@ -205,15 +202,15 @@ class TracePoint # - # A convenience method for TracePoint.new, that activates the trace + # A convenience method for TracePoint.new that activates the trace # automatically. # # trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] } # #=> # # - # trace.enabled? #=> true + # trace.enabled? #=> true # def self.trace: (*_ToSym events) { (instance tp) -> void } -> instance @@ -221,9 +218,9 @@ class TracePoint # rdoc-file=trace_point.rb # - binding() # --> - # Return the generated binding object from event. + # Returns the generated binding object from the event. # - # Note that for `:c_call` and `:c_return` events, the method will return `nil`, + # Note that for `:c_call` and `:c_return` events, the method returns `nil`, # since C methods themselves do not have bindings. # def binding: () -> Binding? @@ -232,7 +229,7 @@ class TracePoint # rdoc-file=trace_point.rb # - callee_id() # --> - # Return the called name of the method being called + # Returns the called name of the method being called. # def callee_id: () -> Symbol? @@ -240,7 +237,7 @@ class TracePoint # rdoc-file=trace_point.rb # - defined_class() # --> - # Return class or module of the method being called. + # Returns the class or module of the method being called. # # class C; def foo; end; end # trace = TracePoint.new(:call) do |tp| @@ -249,20 +246,20 @@ class TracePoint # C.new.foo # end # - # If method is defined by a module, then that module is returned. + # If the method is defined by a module, then that module is returned. # # module M; def foo; end; end - # class C; include M; end; + # class C; include M; end # trace = TracePoint.new(:call) do |tp| # p tp.defined_class #=> M # end.enable do # C.new.foo # end # - # **Note:** #defined_class returns singleton class. + # **Note:** #defined_class returns the singleton class. # - # 6th block parameter of Kernel#set_trace_func passes original class of attached - # by singleton class. + # The 6th block parameter of Kernel#set_trace_func passes the original class + # attached by the singleton class. # # **This is a difference between Kernel#set_trace_func and TracePoint.** # @@ -277,31 +274,30 @@ class TracePoint # - # Deactivates the trace + # Deactivates the trace. # - # Return true if trace was enabled. Return false if trace was disabled. + # Returns `true` if the trace was enabled. Returns `false` if the trace was + # disabled. # - # trace.enabled? #=> true - # trace.disable #=> true (previous status) - # trace.enabled? #=> false - # trace.disable #=> false + # trace.enabled? #=> true + # trace.disable #=> true (previous status) + # trace.enabled? #=> false + # trace.disable #=> false # - # If a block is given, the trace will only be disable within the scope of the + # If a block is given, the trace will only be disabled within the scope of the # block. # - # trace.enabled? - # #=> true + # trace.enabled? #=> true # # trace.disable do - # trace.enabled? - # # only disabled for this block + # trace.enabled? + # # Only disabled for this block # end # - # trace.enabled? - # #=> true + # trace.enabled? #=> true # # Note: You cannot access event hooks within the block. # @@ -313,12 +309,13 @@ class TracePoint # # Activates the trace. # - # Returns `true` if trace was enabled. Returns `false` if trace was disabled. + # Returns `true` if the trace was enabled. Returns `false` if the trace was + # disabled. # # trace.enabled? #=> false # trace.enable #=> false (previous state) @@ -327,24 +324,22 @@ class TracePoint # trace.enable #=> true (previous state) # # trace is still enabled # - # If a block is given, the trace will only be enabled during the block call. If - # target and target_line are both nil, then target_thread will default to the - # current thread if a block is given. + # If a block is given, the trace will only be enabled during the block + # execution. If target and target_line are both nil, then target_thread will + # default to the current thread if a block is given. # - # trace.enabled? - # #=> false + # trace.enabled? #=> false # # trace.enable do # trace.enabled? - # # only enabled for this block and thread + # # Only enabled for this block and thread # end # - # trace.enabled? - # #=> false + # trace.enabled? #=> false # - # `target`, `target_line` and `target_thread` parameters are used to limit - # tracing only to specified code objects. `target` should be a code object for - # which RubyVM::InstructionSequence.of will return an instruction sequence. + # The `target`, `target_line`, and `target_thread` parameters are used to limit + # tracing to specified code objects. `target` should be a code object for which + # RubyVM::InstructionSequence.of will return an instruction sequence. # # t = TracePoint.new(:line) { |tp| p tp } # @@ -359,9 +354,9 @@ class TracePoint # t.enable(target: method(:m1)) # # m1 - # # prints # + # # Prints # # m2 - # # prints nothing + # # Prints nothing # # Note: You cannot access event hooks within the `enable` block. # @@ -373,9 +368,9 @@ class TracePoint # - # The current status of the trace + # Returns the current status of the trace. # def enabled?: () -> bool @@ -383,7 +378,7 @@ class TracePoint # rdoc-file=trace_point.rb # - event() # --> - # Type of event + # Returns the type of event. # # See TracePoint@Events for more information. # @@ -391,9 +386,9 @@ class TracePoint # - # Return a string containing a human-readable TracePoint status. + # Returns a string containing a human-readable TracePoint status. # def inspect: () -> String @@ -401,7 +396,7 @@ class TracePoint # rdoc-file=trace_point.rb # - lineno() # --> - # Line number of the event + # Returns the line number of the event. # def lineno: () -> Integer @@ -409,7 +404,7 @@ class TracePoint # rdoc-file=trace_point.rb # - method_id() # --> - # Return the name at the definition of the method being called + # Returns the name at the definition of the method being called. # def method_id: () -> Symbol? @@ -417,7 +412,7 @@ class TracePoint # rdoc-file=trace_point.rb # - path() # --> - # Path of the file being run + # Returns the path of the file being executed. # def path: () -> String @@ -425,8 +420,8 @@ class TracePoint # rdoc-file=trace_point.rb # - parameters() # --> - # Return the parameters definition of the method or block that the current hook - # belongs to. Format is the same as for Method#parameters + # Returns the parameter definitions of the method or block that the current hook + # belongs to. The format is the same as for Method#parameters. # def parameters: () -> Method::param_types? @@ -434,7 +429,7 @@ class TracePoint # rdoc-file=trace_point.rb # - raised_exception() # --> - # Value from exception raised on the `:raise` event, or rescued on the `:rescue` + # Returns the exception raised on the `:raise` event or rescued on the `:rescue` # event. # def raised_exception: () -> Exception @@ -443,7 +438,7 @@ class TracePoint # rdoc-file=trace_point.rb # - return_value() # --> - # Return value from `:return`, `:c_return`, and `:b_return` event + # Returns the return value from `:return`, `:c_return`, and `:b_return` events. # def return_value: () -> untyped @@ -451,9 +446,9 @@ class TracePoint # rdoc-file=trace_point.rb # - self() # --> - # Return the trace object during event + # Returns the trace object during the event. # - # Same as the following, except it returns the correct object (the method + # Similar to the following, but it returns the correct object (the method # receiver) for `:c_call` and `:c_return` events: # # trace.binding.eval('self') @@ -464,8 +459,8 @@ class TracePoint # rdoc-file=trace_point.rb # - eval_script() # --> - # Compiled source code (String) on *eval methods on the `:script_compiled` - # event. If loaded from a file, it will return nil. + # Returns the compiled source code (String) from eval methods on the + # `:script_compiled` event. If loaded from a file, it returns `nil`. # def eval_script: () -> String? @@ -473,10 +468,10 @@ class TracePoint # rdoc-file=trace_point.rb # - instruction_sequence() # --> - # Compiled instruction sequence represented by a RubyVM::InstructionSequence - # instance on the `:script_compiled` event. + # Returns the compiled instruction sequence represented by a + # RubyVM::InstructionSequence instance on the `:script_compiled` event. # - # Note that this method is MRI specific. + # Note that this method is CRuby-specific. # def instruction_sequence: () -> RubyVM::InstructionSequence end diff --git a/stdlib/date/0/date.rbs b/stdlib/date/0/date.rbs index 8366fbeca..8c50184bf 100644 --- a/stdlib/date/0/date.rbs +++ b/stdlib/date/0/date.rbs @@ -5,7 +5,7 @@ # # * You need both dates and times; Date handles only dates. # * You need only Gregorian dates (and not Julian dates); see [Julian and -# Gregorian Calendars](rdoc-ref:calendars.rdoc). +# Gregorian Calendars](rdoc-ref:date/calendars.rdoc). # # A Date object, once created, is immutable, and cannot be modified. # @@ -88,7 +88,7 @@ class Date # number of days in the month; when the argument is negative, counts backward # from the end of the month. # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd. # @@ -309,7 +309,7 @@ class Date # Date.commercial(2020, 1, 1).to_s # => "2019-12-30" # Date.commercial(2020, 1, 7).to_s # => "2020-01-05" # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new, Date.ordinal. # @@ -343,7 +343,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._httpdate (returns a hash). @@ -364,7 +364,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._iso8601 (returns a hash). @@ -393,7 +393,7 @@ class Date # # Date.jd(Date::ITALY - 1).julian? # => true # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.new. # @@ -417,7 +417,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._jisx0301 (returns a hash). @@ -480,7 +480,7 @@ class Date # # Raises an exception if `yday` is zero or out of range. # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new. # @@ -510,7 +510,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._parse (returns a hash). @@ -531,7 +531,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc2822 (returns a hash). @@ -551,7 +551,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc3339 (returns a hash). @@ -572,7 +572,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc2822 (returns a hash). @@ -598,7 +598,7 @@ class Date # Times](rdoc-ref:strftime_formatting.rdoc). (Unlike Date.strftime, does not # support flags and width.) # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # See also [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html). # @@ -614,7 +614,7 @@ class Date # # Date.today.to_s # => "2022-07-06" # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # def self.today: (?Integer start) -> Date @@ -629,7 +629,7 @@ class Date # Date.valid_date?(2001, 2, 29) # => false # Date.valid_date?(2001, 2, -1) # => true # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new. # @@ -647,7 +647,7 @@ class Date # # See Date.commercial. # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.commercial. # @@ -664,7 +664,7 @@ class Date # Date.valid_date?(2001, 2, 29) # => false # Date.valid_date?(2001, 2, -1) # => true # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.new. # @@ -679,7 +679,7 @@ class Date # # Date.valid_jd?(2451944) # => true # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd. # @@ -695,7 +695,7 @@ class Date # Date.valid_ordinal?(2001, 34) # => true # Date.valid_ordinal?(2001, 366) # => false # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # # Related: Date.jd, Date.ordinal. # @@ -714,7 +714,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._xmlschema (returns a hash). @@ -1225,7 +1225,7 @@ class Date # d1 = d0.new_start(Date::JULIAN) # d1.julian? # => true # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # def new_start: (?Integer start) -> Date @@ -1322,7 +1322,7 @@ class Date # # See: # - # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # * Argument [limit](rdoc-ref:Date@Argument+limit). # # Related: Date._rfc2822 (returns a hash). @@ -1355,7 +1355,7 @@ class Date # Date.new(2001, 2, 3, Date::GREGORIAN).start # => -Infinity # Date.new(2001, 2, 3, Date::JULIAN).start # => Infinity # - # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start). # def start: () -> Float diff --git a/stdlib/net-http/0/net-http.rbs b/stdlib/net-http/0/net-http.rbs index 9d70684d8..0f91eeb60 100644 --- a/stdlib/net-http/0/net-http.rbs +++ b/stdlib/net-http/0/net-http.rbs @@ -487,8 +487,7 @@ module Net # # * [::start](rdoc-ref:Net::HTTP.start): Begins a new session in a new # Net::HTTP object. - # * [#started?](rdoc-ref:Net::HTTP#started?) (aliased as - # [#active?](rdoc-ref:Net::HTTP#active?)): Returns whether in a session. + # * [#started?](rdoc-ref:Net::HTTP#started?): Returns whether in a session. # * [#finish](rdoc-ref:Net::HTTP#finish): Ends an active session. # * [#start](rdoc-ref:Net::HTTP#start): Begins a new session in an existing # Net::HTTP object (`self`). @@ -562,18 +561,15 @@ module Net # object. # * [#request](rdoc-ref:Net::HTTP#request): Sends a request and returns a # response object. - # * [#request_get](rdoc-ref:Net::HTTP#request_get) (aliased as - # [#get2](rdoc-ref:Net::HTTP#get2)): Sends a GET request and forms a - # response object; if a block given, calls the block with the object, - # otherwise returns the object. - # * [#request_head](rdoc-ref:Net::HTTP#request_head) (aliased as - # [#head2](rdoc-ref:Net::HTTP#head2)): Sends a HEAD request and forms a - # response object; if a block given, calls the block with the object, - # otherwise returns the object. - # * [#request_post](rdoc-ref:Net::HTTP#request_post) (aliased as - # [#post2](rdoc-ref:Net::HTTP#post2)): Sends a POST request and forms a - # response object; if a block given, calls the block with the object, - # otherwise returns the object. + # * [#request_get](rdoc-ref:Net::HTTP#request_get): Sends a GET request and + # forms a response object; if a block given, calls the block with the + # object, otherwise returns the object. + # * [#request_head](rdoc-ref:Net::HTTP#request_head): Sends a HEAD request and + # forms a response object; if a block given, calls the block with the + # object, otherwise returns the object. + # * [#request_post](rdoc-ref:Net::HTTP#request_post): Sends a POST request and + # forms a response object; if a block given, calls the block with the + # object, otherwise returns the object. # * [#send_request](rdoc-ref:Net::HTTP#send_request): Sends a request and # returns a response object. # * [#trace](rdoc-ref:Net::HTTP#trace): Sends a TRACE request and returns a @@ -605,8 +601,8 @@ module Net # * [::proxy_class?](rdoc-ref:Net::HTTP.proxy_class?): Returns whether `self` # is a proxy class. # * [#proxy?](rdoc-ref:Net::HTTP#proxy?): Returns whether `self` has a proxy. - # * [#proxy_address](rdoc-ref:Net::HTTP#proxy_address) (aliased as - # [#proxyaddr](rdoc-ref:Net::HTTP#proxyaddr)): Returns the proxy address. + # * [#proxy_address](rdoc-ref:Net::HTTP#proxy_address): Returns the proxy + # address. # * [#proxy_from_env?](rdoc-ref:Net::HTTP#proxy_from_env?): Returns whether # the proxy is taken from an environment variable. # * [:proxy_from_env=](rdoc-ref:Net::HTTP#proxy_from_env=): Sets whether the @@ -709,7 +705,6 @@ module Net # ### HTTP Version # # * [::version_1_2?](rdoc-ref:Net::HTTP.version_1_2?) (aliased as - # [::is_version_1_2?](rdoc-ref:Net::HTTP.is_version_1_2?) and # [::version_1_2](rdoc-ref:Net::HTTP.version_1_2)): Returns true; retained # for compatibility. # @@ -1359,16 +1354,15 @@ module Net # # Sets or returns the available SSL ciphers. See - # [OpenSSL::SSL::SSLContext#ciphers=](rdoc-ref:OpenSSL::SSL::SSLContext#ciphers- - # 3D). + # [:SSL::SSLContext#ciphers=](OpenSSL::SSL::SSL::Context#ciphers=). # attr_accessor ciphers: untyped # # Sets or returns the extra X509 certificates to be added to the certificate # chain. See - # [OpenSSL::SSL::SSLContext#add_certificate](rdoc-ref:OpenSSL::SSL::SSLContext#a - # dd_certificate). + # [:SSL::SSLContext#add_certificate](OpenSSL::SSL::SSL::Context#add_certificate) + # . # attr_accessor extra_chain_cert: untyped @@ -1384,22 +1378,19 @@ module Net # # Sets or returns the SSL version. See - # [OpenSSL::SSL::SSLContext#ssl_version=](rdoc-ref:OpenSSL::SSL::SSLContext#ssl_ - # version-3D). + # [:SSL::SSLContext#ssl_version=](OpenSSL::SSL::SSL::Context#ssl_version=). # attr_accessor ssl_version: untyped # # Sets or returns the minimum SSL version. See - # [OpenSSL::SSL::SSLContext#min_version=](rdoc-ref:OpenSSL::SSL::SSLContext#min_ - # version-3D). + # [:SSL::SSLContext#min_version=](OpenSSL::SSL::SSL::Context#min_version=). # attr_accessor min_version: untyped # # Sets or returns the maximum SSL version. See - # [OpenSSL::SSL::SSLContext#max_version=](rdoc-ref:OpenSSL::SSL::SSLContext#max_ - # version-3D). + # [:SSL::SSLContext#max_version=](OpenSSL::SSL::SSL::Context#max_version=). # attr_accessor max_version: untyped @@ -1423,8 +1414,8 @@ module Net # # Sets or returns whether to verify that the server certificate is valid for the # hostname. See - # [OpenSSL::SSL::SSLContext#verify_hostname=](rdoc-ref:OpenSSL::SSL::SSLContext# - # attribute-i-verify_mode). + # [:SSL::SSLContext#verify_hostname=](OpenSSL::SSL::SSL::Context#verify_hostname + # =). # attr_accessor verify_hostname: untyped diff --git a/stdlib/rdoc/0/rdoc.rbs b/stdlib/rdoc/0/rdoc.rbs index 11d72e3d9..a5fa214ac 100644 --- a/stdlib/rdoc/0/rdoc.rbs +++ b/stdlib/rdoc/0/rdoc.rbs @@ -1,9 +1,3 @@ -# -# Gem::RDoc provides methods to generate RDoc and ri data for installed gems -# upon gem installation. -# -# This file is automatically required by RubyGems 1.9 and newer. -# # # RDoc produces documentation for Ruby source files by parsing the source and # extracting the definition for classes, modules, methods, includes and @@ -55,6 +49,18 @@ # of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby parser # for irb and the rtags package. # +# +# This class is referenced by RubyGems to create documents. All implementations +# are moved to the above RubyGemsHook. +# +# This class does nothing when this RDoc is installed as a normal gem or a +# bundled gem. +# +# This class does generate/remove documents for compatibility when this RDoc is +# installed as a default gem. +# +# We can remove this when all maintained RubyGems remove `rubygems/rdoc.rb`. +# module RDoc # # A TokenStream is a list of tokens, gathered during the parse of some entity diff --git a/stdlib/resolv/0/resolv.rbs b/stdlib/resolv/0/resolv.rbs index e5b49724a..98885bc2b 100644 --- a/stdlib/resolv/0/resolv.rbs +++ b/stdlib/resolv/0/resolv.rbs @@ -126,10 +126,14 @@ class Resolv # # Creates a new Resolv using `resolvers`. # + # If `resolvers` is not given, a hash, or `nil`, uses a Hosts resolver and and a + # DNS resolver. If `resolvers` is a hash, uses the hash as configuration for + # the DNS resolver. + # def initialize: (?Resolv::Hosts | Resolv::DNS resolvers) -> untyped end diff --git a/stdlib/securerandom/0/securerandom.rbs b/stdlib/securerandom/0/securerandom.rbs index 7a7d42908..5b471d97f 100644 --- a/stdlib/securerandom/0/securerandom.rbs +++ b/stdlib/securerandom/0/securerandom.rbs @@ -37,6 +37,13 @@ module SecureRandom extend Random::Formatter + # + # Compatibility methods for Ruby 3.2, we can remove this after dropping to + # support Ruby 3.2 + # def self.alphanumeric: (?Integer?) -> String def self.base64: (?Integer?) -> String diff --git a/stdlib/socket/0/socket.rbs b/stdlib/socket/0/socket.rbs index a84cc3e2d..5e5542485 100644 --- a/stdlib/socket/0/socket.rbs +++ b/stdlib/socket/0/socket.rbs @@ -462,8 +462,13 @@ class Socket < BasicSocket # Version 2 ([RFC 8305](https://datatracker.ietf.org/doc/html/rfc8305)) # algorithm by default. # + # For details on Happy Eyeballs Version 2, see + # [Socket.tcp_fast_fallback=](rdoc-ref:Socket.tcp_fast_fallback=). + # # To make it behave the same as in Ruby 3.3 and earlier, explicitly specify the - # option `fast_fallback:false`. + # option fast_fallback:false. Or, setting Socket.tcp_fast_fallback=false will + # disable Happy Eyeballs Version 2 not only for this method but for all Socket + # globally. # # If local_host:local_port is given, the socket is bound to it. # @@ -498,31 +503,6 @@ class Socket < BasicSocket # puts sock.read # } # - # ### Happy Eyeballs Version 2 - # Happy Eyeballs Version 2 ([RFC - # 8305](https://datatracker.ietf.org/doc/html/rfc8305)) is an algorithm designed - # to improve client socket connectivity. - # It aims for more reliable and efficient connections by performing hostname - # resolution and connection attempts in parallel, instead of serially. - # - # Starting from Ruby 3.4, this method operates as follows with this algorithm: - # - # 1. Start resolving both IPv6 and IPv4 addresses concurrently. - # 2. Start connecting to the one of the addresses that are obtained first. - # If IPv4 addresses are obtained first, the method waits 50 ms for IPv6 name - # resolution to prioritize IPv6 connections. - # 3. After starting a connection attempt, wait 250 ms for the connection to be - # established. - # If no connection is established within this time, a new connection is - # started every 250 ms - # until a connection is established or there are no more candidate - # addresses. - # (Although RFC 8305 strictly specifies sorting addresses, - # this method only alternates between IPv6 / IPv4 addresses due to the - # performance concerns) - # 4. Once a connection is established, all remaining connection attempts are - # canceled. - # def self.tcp: (String host, Integer port, ?String local_host, ?Integer local_port, ?resolv_timeout: Time::_Timeout, ?connect_timeout: Time::_Timeout) -> instance | (String host, Integer port, ?String local_host, ?Integer local_port, ?resolv_timeout: Time::_Timeout, ?connect_timeout: Time::_Timeout) { (instance) -> void } -> void @@ -1077,7 +1057,8 @@ class Socket < BasicSocket # otherwise an exception is raised. # # ### Parameter - # # +remote_sockaddr+ - the +struct+ sockaddr contained in a string or Addrinfo object + # * `remote_sockaddr` - the `struct` sockaddr contained in a string or + # Addrinfo object # # ### Example: # # Pull down Google's web page @@ -1112,7 +1093,7 @@ class Socket < BasicSocket # the symbol `:wait_writable` instead. # # ### See - # # Socket#connect + # * Socket#connect # def connect_nonblock: (untyped addr, ?exception: untyped) -> (Integer | :wait_writable) diff --git a/stdlib/socket/0/tcp_socket.rbs b/stdlib/socket/0/tcp_socket.rbs index 39089c4fd..3c4175346 100644 --- a/stdlib/socket/0/tcp_socket.rbs +++ b/stdlib/socket/0/tcp_socket.rbs @@ -48,11 +48,16 @@ class TCPSocket < IPSocket # Version 2 ([RFC 8305](https://datatracker.ietf.org/doc/html/rfc8305)) # algorithm by default, except on Windows. # + # For details on Happy Eyeballs Version 2, see + # [Socket.tcp_fast_fallback=](rdoc-ref:Socket.tcp_fast_fallback=). + # # To make it behave the same as in Ruby 3.3 and earlier, explicitly specify the - # option `fast_fallback:false`. + # option fast_fallback:false. Or, setting Socket.tcp_fast_fallback=false will + # disable Happy Eyeballs Version 2 not only for this method but for all Socket + # globally. # - # Happy Eyeballs Version 2 is not provided on Windows, and it behaves the same - # as in Ruby 3.3 and earlier. + # When using TCPSocket.new on Windows, Happy Eyeballs Version 2 is not provided, + # and it behaves the same as in Ruby 3.3 and earlier. # # :resolv_timeout # : Specifies the timeout in seconds from when the hostname resolution starts. @@ -70,32 +75,5 @@ class TCPSocket < IPSocket # :fast_fallback # : Enables the Happy Eyeballs Version 2 algorithm (enabled by default). # - # - # ### Happy Eyeballs Version 2 - # Happy Eyeballs Version 2 ([RFC - # 8305](https://datatracker.ietf.org/doc/html/rfc8305)) is an algorithm designed - # to improve client socket connectivity. - # It aims for more reliable and efficient connections by performing hostname - # resolution and connection attempts in parallel, instead of serially. - # - # Starting from Ruby 3.4, this method operates as follows with this algorithm - # except on Windows: - # - # 1. Start resolving both IPv6 and IPv4 addresses concurrently. - # 2. Start connecting to the one of the addresses that are obtained first. - # If IPv4 addresses are obtained first, the method waits 50 ms for IPv6 name - # resolution to prioritize IPv6 connections. - # 3. After starting a connection attempt, wait 250 ms for the connection to be - # established. - # If no connection is established within this time, a new connection is - # started every 250 ms - # until a connection is established or there are no more candidate - # addresses. - # (Although RFC 8305 strictly specifies sorting addresses, - # this method only alternates between IPv6 / IPv4 addresses due to the - # performance concerns) - # 4. Once a connection is established, all remaining connection attempts are - # canceled. - # def initialize: (String remote_host, Integer remote_port, ?String local_host, ?Integer local_port) -> untyped end