rbs 3.7.0 → 3.8.0.pre.1

data/stdlib/optparse/0/optparse.rbs

@@ -21,7 +21,6 @@
 # 4.  Arguments can be automatically converted to a specified class.
 # 5.  Arguments can be restricted to a certain set.
 #
-#
 # All of these features are demonstrated in the examples below.  See
 # #make_switch for full documentation.
 #
@@ -129,7 +128,6 @@
 # *   Array -- Strings separated by ',' (e.g. 1,2,3)
 # *   Regexp -- Regular expressions. Also includes options.
 #
-#
 # We can also add our own coercions, which we will cover below.
 #
 # #### Using Built-in Conversions
@@ -431,6 +429,7 @@ class OptionParser
   #   rdoc-file=lib/optparse.rb
   #   - terminate(arg = nil)
   # -->
+  # See #terminate.
   #
   def self.terminate: (?String arg) -> bot
 
@@ -438,6 +437,9 @@ class OptionParser
   #   rdoc-file=lib/optparse.rb
   #   - top()
   # -->
+  # Returns the global top option list.
+  #
+  # Do not use directly.
   #
   def self.top: () -> OptionParser::List
 
@@ -458,6 +460,13 @@ class OptionParser
   #   rdoc-file=lib/optparse.rb
   #   - abort(mesg = $!)
   # -->
+  # Shows message with the program name then aborts.
+  #
+  # `mesg`
+  # :   Message, defaulted to +$!+.
+  #
+  #
+  # See Kernel#abort.
   #
   def abort: (?_ToS mesg) -> bot
 
@@ -470,6 +479,7 @@ class OptionParser
   #
   # `t`
   # :   Argument class specifier, any object including Class.
+  #
   # `pat`
   # :   Pattern for argument, defaults to `t` if it responds to match.
   #
@@ -505,6 +515,7 @@ class OptionParser
   #   rdoc-file=lib/optparse.rb
   #   - candidate(word)
   # -->
+  # Return candidates for `word`.
   #
   def candidate: (String word) -> Array[untyped]
 
@@ -589,7 +600,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - environment(env = File.basename($0, '.*'))
+  #   - environment(env = File.basename($0, '.*'), **keywords)
   # -->
   # Parses environment variable `env` or its uppercase with splitting like a
   # shell.
@@ -600,7 +611,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - getopts(*args, symbolize_names: false)
+  #   - getopts(*args, symbolize_names: false, **keywords)
   # -->
   # Wrapper method for getopts.rb.
   #
@@ -636,12 +647,13 @@ class OptionParser
   #   rdoc-file=lib/optparse.rb
   #   - inc(*args)
   # -->
+  # See self.inc
   #
   def inc: (*untyped args) -> untyped
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - load(filename = nil, into: nil)
+  #   - load(filename = nil, **keywords)
   # -->
   # Loads options from file names as `filename`. Does nothing when the file is not
   # present. Returns whether successfully loaded.
@@ -675,6 +687,9 @@ class OptionParser
   # -->
   # Pushes a new List.
   #
+  # If a block is given, yields `self` and returns the result of the block,
+  # otherwise returns `self`.
+  #
   def new: () -> self
          | [T] () { (self) -> T } -> T
 
@@ -741,7 +756,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - order(*argv, into: nil, &nonopt)
+  #   - order(*argv, **keywords, &nonopt)
   # -->
   # Parses command line arguments `argv` in order. When a block is given, each
   # non-option argument is yielded. When optional `into` keyword argument is
@@ -755,7 +770,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - order!(argv = default_argv, into: nil, &nonopt)
+  #   - order!(argv = default_argv, into: nil, **keywords, &nonopt)
   # -->
   # Same as #order, but removes switches destructively. Non-option arguments
   # remain in `argv`.
@@ -764,7 +779,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - parse(*argv, into: nil)
+  #   - parse(*argv, **keywords)
   # -->
   # Parses command line arguments `argv` in order when environment variable
   # POSIXLY_CORRECT is set, and in permutation mode otherwise. When optional
@@ -776,7 +791,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - parse!(argv = default_argv, into: nil)
+  #   - parse!(argv = default_argv, **keywords)
   # -->
   # Same as #parse, but removes switches destructively. Non-option arguments
   # remain in `argv`.
@@ -785,7 +800,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - permute(*argv, into: nil)
+  #   - permute(*argv, **keywords)
   # -->
   # Parses command line arguments `argv` in permutation mode and returns list of
   # non-option arguments. When optional `into` keyword argument is provided, the
@@ -797,7 +812,7 @@ class OptionParser
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - permute!(argv = default_argv, into: nil)
+  #   - permute!(argv = default_argv, **keywords)
   # -->
   # Same as #permute, but removes switches destructively. Non-option arguments
   # remain in `argv`.
@@ -816,11 +831,11 @@ class OptionParser
   # -->
   # Directs to reject specified class argument.
   #
-  # `t`
+  # `type`
   # :   Argument class specifier, any object including Class.
   #
   #
-  #     reject(t)
+  #     reject(type)
   #
   def reject: (Class t) -> void
 
@@ -884,10 +899,13 @@ class OptionParser
   #
   # `to`
   # :   Output destination, which must have method <<. Defaults to [].
+  #
   # `width`
   # :   Width of left side, defaults to @summary_width.
+  #
   # `max`
   # :   Maximum length allowed for left side, defaults to `width` - 1.
+  #
   # `indent`
   # :   Indentation, defaults to @summary_indent.
   #
@@ -952,6 +970,13 @@ class OptionParser
   #   rdoc-file=lib/optparse.rb
   #   - warn(mesg = $!)
   # -->
+  # Shows warning message with the program name
+  #
+  # `mesg`
+  # :   Message, defaulted to +$!+.
+  #
+  #
+  # See Kernel#warn.
   #
   def warn: (?_ToS mesg) -> void
 
@@ -983,8 +1008,10 @@ class OptionParser
   #
   # `banner`
   # :   Banner message.
+  #
   # `width`
   # :   Summary width.
+  #
   # `indent`
   # :   Summary indent.
   #
@@ -1064,6 +1091,9 @@ OptionParser::RequiredArgument: Array[untyped]
 
 OptionParser::SPLAT_PROC: Proc
 
+# <!-- rdoc-file=lib/optparse.rb -->
+# The version string
+#
 OptionParser::Version: String
 
 # <!-- rdoc-file=lib/optparse.rb -->
@@ -1109,7 +1139,7 @@ module OptionParser::Arguable
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - getopts(*args, symbolize_names: false)
+  #   - getopts(*args, symbolize_names: false, **keywords)
   # -->
   # Substitution of getopts is possible as follows. Also see OptionParser#getopts.
   #
@@ -1148,7 +1178,7 @@ module OptionParser::Arguable
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - order!(&blk)
+  #   - order!(**keywords, &blk)
   # -->
   # Parses `self` destructively in order and returns `self` containing the rest
   # arguments left unparsed.
@@ -1157,7 +1187,7 @@ module OptionParser::Arguable
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - parse!()
+  #   - parse!(**keywords)
   # -->
   # Parses `self` destructively and returns `self` containing the rest arguments
   # left unparsed.
@@ -1166,7 +1196,7 @@ module OptionParser::Arguable
 
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - permute!()
+  #   - permute!(**keywords)
   # -->
   # Parses `self` destructively in permutation mode and returns `self` containing
   # the rest arguments left unparsed.
@@ -1271,10 +1301,13 @@ class OptionParser::List
   #
   # `switch`
   # :   OptionParser::Switch instance to be inserted.
+  #
   # `short_opts`
   # :   List of short style options.
+  #
   # `long_opts`
   # :   List of long style options.
+  #
   # `nolong_opts`
   # :   List of long style options with "no-" prefix.
   #
@@ -1334,10 +1367,13 @@ class OptionParser::List
   #
   # `switch`
   # :   OptionParser::Switch instance to be inserted.
+  #
   # `short_opts`
   # :   List of short style options.
+  #
   # `long_opts`
   # :   List of long style options.
+  #
   # `nolong_opts`
   # :   List of long style options with "no-" prefix.
   #
@@ -1570,13 +1606,17 @@ class OptionParser::Switch
   #
   # `sdone`
   # :   Already summarized short style options keyed hash.
+  #
   # `ldone`
   # :   Already summarized long style options keyed hash.
+  #
   # `width`
   # :   Width of left side (option part). In other words, the right side
   #     (description part) starts after `width` columns.
+  #
   # `max`
   # :   Maximum width of left side -> the options are filled within `max` columns.
+  #
   # `indent`
   # :   Prefix string indents all summarized lines.
   #
@@ -1677,7 +1717,7 @@ end
 class OptionParser::Switch::RequiredArgument < OptionParser::Switch
   # <!--
   #   rdoc-file=lib/optparse.rb
-  #   - parse(arg, argv)
+  #   - parse(arg, argv, &_)
   # -->
   # Raises an exception if argument is not present.
   #

data/stdlib/pathname/0/pathname.rbs

@@ -82,7 +82,6 @@
 # *   #each_child
 # *   #mountpoint?
 #
-#
 # ### File status predicate methods
 #
 # These methods are a facade for FileTest:
@@ -111,7 +110,6 @@
 # *   #writable_real?
 # *   #zero?
 #
-#
 # ### File property and manipulation methods
 #
 # These methods are a facade for File:
@@ -142,7 +140,6 @@
 # *   #expand_path(*args)
 # *   #split
 #
-#
 # ### Directory methods
 #
 # These methods are a facade for Dir:
@@ -154,7 +151,6 @@
 # *   #mkdir(*args)
 # *   #opendir(*args)
 #
-#
 # ### IO
 #
 # These methods are a facade for IO:
@@ -166,7 +162,6 @@
 # *   #write(*args)
 # *   #binwrite(*args)
 #
-#
 # ### Utilities
 #
 # These methods are a mixture of Find, FileUtils, and others:
@@ -175,7 +170,6 @@
 # *   #rmtree
 # *   #unlink / #delete
 #
-#
 # ## Method documentation
 #
 # As the above section shows, most of the methods in Pathname are facades.  The
@@ -901,7 +895,7 @@ class Pathname
   #
   # See FileUtils.mkpath and FileUtils.mkdir_p
   #
-  def mkpath: () -> nil
+  def mkpath: () -> self
 
   # <!--
   #   rdoc-file=ext/pathname/lib/pathname.rb
@@ -1112,7 +1106,7 @@ class Pathname
   #
   # See FileUtils.rm_rf
   #
-  def rmtree: () -> void
+  def rmtree: () -> self
 
   # <!--
   #   rdoc-file=ext/pathname/lib/pathname.rb

data/stdlib/pp/0/pp.rbs

@@ -72,6 +72,9 @@ class PP < PrettyPrint
     def group: (?Integer indent, ?String open_obj, ?String close_obj, ?Integer open_width, ?Integer close_width) { () -> untyped } -> void
   end
 
+  # <!-- rdoc-file=lib/pp.rb -->
+  # Module that defines helper methods for pretty_print.
+  #
   module PPMethods : _PPMethodsRequired
     # <!--
     #   rdoc-file=lib/pp.rb
@@ -222,7 +225,6 @@ class PP < PrettyPrint
   #     variable is assumed to be set to the width.
   # 3.  If `COLUMN` is not set to a non-zero number, 80 is assumed.
   #
-  #
   # And finally, returns the above width value - 1.
   # *   This -1 is for Windows command prompt, which moves the cursor to the next
   #     line if it reaches the last column.

data/stdlib/prettyprint/0/prettyprint.rbs

@@ -9,18 +9,15 @@
 # *   optional width argument for PrettyPrint#text
 # *   PrettyPrint#breakable
 #
-#
 # There are several candidate uses:
 # *   text formatting using proportional fonts
 # *   multibyte characters which has columns different to number of bytes
 # *   non-string formatting
 #
-#
 # ## Bugs
 # *   Box based formatting?
 # *   Other (better) model/algorithm?
 #
-#
 # Report any bugs at http://bugs.ruby-lang.org
 #
 # ## References
@@ -316,7 +313,6 @@ class PrettyPrint
   # *   #flush
   # *   #first?
   #
-  #
   # but instead, the output has no line breaks
   #
   class SingleLine

data/stdlib/pstore/0/pstore.rbs

@@ -21,7 +21,6 @@
 #     collection of prospective changes to the store; a transaction is defined
 #     in the block given with a call to PStore#transaction.
 #
-#
 # ## About the Examples
 #
 # Examples on this page need a store that has known properties. They can get a
@@ -73,7 +72,6 @@
 #     must also be Marshal-able. See [Hierarchical
 #     Values](rdoc-ref:PStore@Hierarchical+Values).
 #
-#
 # ## Transactions
 #
 # ### The Transaction Block
@@ -104,7 +102,6 @@
 # *   Is the only context where methods that read from or write to the store are
 #     allowed.
 #
-#
 # As seen above, changes in a transaction are made automatically when the block
 # exits. The block may be exited early by calling method #commit or #abort.
 #
@@ -138,7 +135,6 @@
 #           end
 #         end
 #
-#
 # ### Read-Only Transactions
 #
 # By default, a transaction allows both reading from and writing to the store:
@@ -250,7 +246,6 @@
 # *   Optional argument `thread_safe` at method PStore.new.
 # *   Attribute #ultra_safe.
 #
-#
 # Needless to say, if you're storing valuable data with PStore, then you should
 # backup the PStore file from time to time.
 #
@@ -403,7 +398,6 @@ class PStore
   #           end
   #         end
   #
-  #
   # Raises an exception if called outside a transaction block.
   #
   def fetch: (untyped name, ?untyped default) -> untyped

data/stdlib/psych/0/psych.rbs

@@ -219,20 +219,29 @@ module Psych
   #     `0..9` range, otherwise option is ignored.
   #
   #     Default: `2`.
+  #
   # `:line_width`
-  # :   Max character to wrap line at.
+  # :   Max character to wrap line at. For unlimited line width use `-1`.
   #
   #     Default: `0` (meaning "wrap at 81").
+  #
   # `:canonical`
   # :   Write "canonical" YAML form (very verbose, yet strictly formal).
   #
   #     Default: `false`.
+  #
   # `:header`
   # :   Write `%YAML [version]` at the beginning of document.
   #
   #     Default: `false`.
   #
   #
+  # `:stringify_names`
+  # :   Dump symbol keys in Hash objects as string.
+  #
+  #     Default: `false`.
+  #
+  #
   # Example:
   #
   #     # Dump an array, get back a YAML string
@@ -247,6 +256,9 @@ module Psych
   #     # Dump an array to an IO with indentation set
   #     Psych.dump(['a', ['b']], StringIO.new, indentation: 3)
   #
+  #     # Dump hash with symbol keys as string
+  #     Psych.dump({a: "b"}, stringify_names: true) # => "---\na: b\n"
+  #
   %a{annotate:rdoc:copy:Psych.dump}
   def self.dump: (untyped o, ?indentation: Integer, ?line_width: Integer, ?canonical: bool, ?header: bool) -> String
                | [IO] (untyped o, IO, ?indentation: Integer, ?line_width: Integer, ?canonical: bool, ?header: bool) -> IO
@@ -259,7 +271,7 @@ module Psych
   # the object contained in the first document will be returned. `filename` will
   # be used in the exception message if any exception is raised while parsing.  If
   # `yaml` is empty, it returns the specified `fallback` return value, which
-  # defaults to `false`.
+  # defaults to `nil`.
   #
   # Raises a Psych::SyntaxError when a YAML syntax error is detected.
   #
@@ -293,7 +305,7 @@ module Psych
   # -->
   # Loads the document contained in `filename`.  Returns the yaml contained in
   # `filename` as a Ruby object, or if the file is empty, it returns the specified
-  # `fallback` return value, which defaults to `false`. See load for options.
+  # `fallback` return value, which defaults to `nil`. See load for options.
   #
   %a{annotate:rdoc:copy:Psych.load_file}
   def self.load_file: (string | _ToPath, ?fallback: untyped, ?symbolize_names: bool, ?freeze: bool) -> untyped
@@ -314,7 +326,6 @@ module Psych
   # *   Array
   # *   Hash
   #
-  #
   # Recursive data structures are not allowed by default.  Arbitrary classes can
   # be allowed by adding those classes to the `permitted_classes` keyword
   # argument.  They are additive.  For example, to allow Date deserialization:

data/stdlib/pty/0/pty.rbs

@@ -68,6 +68,7 @@ module PTY
   #
   # `pid`
   # :   The process id of the process to check
+  #
   # `raise`
   # :   If `true` and the process identified by `pid` is no longer alive a
   #     PTY::ChildExited is raised.
@@ -85,9 +86,17 @@ module PTY
   # the spawned pty.
   #
   #     # sets FOO to "bar"
-  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") { |r,w,pid| p r.read } #=> "bar\r\n"
+  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> "bar\r\n"
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
   #     # unsets FOO
-  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") { |r,w,pid| p r.read } #=> ""
+  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> ""
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
   #
   # `command` and `command_line` are the full commands to run, given a String. Any
   # additional `arguments` will be passed to the command.
@@ -101,11 +110,23 @@ module PTY
   # `r`
   # :   A readable IO that contains the command's standard output and standard
   #     error
+  #
   # `w`
   # :   A writable IO that is the command's standard input
+  #
   # `pid`
   # :   The process identifier for the command.
   #
+  #
+  # ### Clean up
+  #
+  # This method does not clean up like closing IOs or waiting for child process,
+  # except that the process is detached in the block form to prevent it from
+  # becoming a zombie (see Process.detach).  Any other cleanup is the
+  # responsibility of the caller.  If waiting for `pid`, be sure to close both `r`
+  # and `w` before doing so; doing it in the reverse order may cause deadlock on
+  # some OSes.
+  #
   alias self.getpty self.spawn
 
   # <!--
@@ -136,6 +157,7 @@ module PTY
   #
   # `master_io`
   # :   the master of the pty, as an IO.
+  #
   # `slave_file`
   # :   the slave of the pty, as a File.  The path to the terminal device is
   #     available via `slave_file.path`
@@ -169,9 +191,17 @@ module PTY
   # the spawned pty.
   #
   #     # sets FOO to "bar"
-  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") { |r,w,pid| p r.read } #=> "bar\r\n"
+  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> "bar\r\n"
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
   #     # unsets FOO
-  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") { |r,w,pid| p r.read } #=> ""
+  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> ""
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
   #
   # `command` and `command_line` are the full commands to run, given a String. Any
   # additional `arguments` will be passed to the command.
@@ -185,11 +215,23 @@ module PTY
   # `r`
   # :   A readable IO that contains the command's standard output and standard
   #     error
+  #
   # `w`
   # :   A writable IO that is the command's standard input
+  #
   # `pid`
   # :   The process identifier for the command.
   #
+  #
+  # ### Clean up
+  #
+  # This method does not clean up like closing IOs or waiting for child process,
+  # except that the process is detached in the block form to prevent it from
+  # becoming a zombie (see Process.detach).  Any other cleanup is the
+  # responsibility of the caller.  If waiting for `pid`, be sure to close both `r`
+  # and `w` before doing so; doing it in the reverse order may cause deadlock on
+  # some OSes.
+  #
   def self.spawn: (*String command) -> [ IO, IO, Integer ]
                 | (*String command) { ([ IO, IO, Integer ]) -> void } -> void
 end

data/stdlib/rdoc/0/code_object.rbs

@@ -15,15 +15,11 @@ module RDoc
   #         *   RDoc::NormalClass
   #         *   RDoc::NormalModule
   #         *   RDoc::SingleClass
-  #
-  #
   # *   RDoc::MethodAttr
   #     *   RDoc::Attr
   #     *   RDoc::AnyMethod
   #         *   RDoc::GhostMethod
   #         *   RDoc::MetaMethod
-  #
-  #
   # *   RDoc::Alias
   # *   RDoc::Constant
   # *   RDoc::Mixin

data/stdlib/rdoc/0/markup.rbs

@@ -11,20 +11,16 @@ module RDoc
   # RDoc::Markup and other markup formats do no output formatting, this is handled
   # by the RDoc::Markup::Formatter subclasses.
   #
-  # # Supported Formats
+  # # Markup Formats
   #
-  # Besides the RDoc::Markup format, the following formats are built in to RDoc:
-  #
-  # markdown
-  # :   The markdown format as described by
-  #     http://daringfireball.net/projects/markdown/.  See RDoc::Markdown for
-  #     details on the parser and supported extensions.
-  # rd
-  # :   The rdtool format.  See RDoc::RD for details on the parser and format.
-  # tomdoc
-  # :   The TomDoc format as described by http://tomdoc.org/.  See RDoc::TomDoc
-  #     for details on the parser and supported extensions.
+  # `RDoc` supports these markup formats:
   #
+  # *   `rdoc`: the `RDoc` markup format; see RDoc::MarkupReference.
+  # *   `markdown`: The `markdown` markup format as described in the [Markdown
+  #     Guide](https://www.markdownguide.org); see RDoc::Markdown.
+  # *   `rd`: the `rd` markup format format; see RDoc::RD.
+  # *   `tomdoc`: the TomDoc format as described in [TomDoc for
+  #     Ruby](http://tomdoc.org); see RDoc::TomDoc.
   #
   # You can choose a markup format using the following methods:
   #
@@ -36,9 +32,11 @@ module RDoc
   #         rdoc --markup your_favorite_format --write-options
   #
   #     and commit `.rdoc_options` and ship it with your packaged gem.
+  #
   # per file
   # :   At the top of the file use the `:markup:` directive to set the default
   #     format for the rest of the file.
+  #
   # per comment
   # :   Use the `:markup:` directive at the top of a comment you want to write in
   #     a different format.

data/stdlib/rdoc/0/rdoc.rbs

@@ -21,8 +21,7 @@
 # If you want to use RDoc to create documentation for your Ruby source files,
 # see RDoc::Markup and refer to `rdoc --help` for command line usage.
 #
-# If you want to set the default markup format see
-# RDoc::Markup@Supported+Formats
+# If you want to set the default markup format see RDoc::Markup@Markup+Formats
 #
 # If you want to store rdoc configuration in your gem (such as the default
 # markup format) see RDoc::Options@Saved+Options