rbs 2.0.0 → 2.1.0

data/stdlib/optparse/0/optparse.rbs

@@ -1,5 +1,10 @@
+# <!-- rdoc-file=lib/optparse.rb -->
 # ## OptionParser
 #
+# ### New to OptionParser?
+#
+# See the [Tutorial](./doc/optparse/tutorial_rdoc.html).
+#
 # ### Introduction
 #
 # OptionParser is a class for command-line option analysis.  It is much more
@@ -368,8 +373,11 @@
 #
 # ### Further documentation
 #
-# The above examples should be enough to learn how to use this class.  If you
-# have any questions, file a ticket at http://bugs.ruby-lang.org.
+# The above examples, along with the accompanying
+# [Tutorial](./doc/optparse/tutorial_rdoc.html), should be enough to learn how
+# to use this class. If you have any questions, file a ticket at
+# http://bugs.ruby-lang.org.
+#
 class OptionParser
   interface _Pattern
     def match: (untyped other) -> boolish
@@ -383,27 +391,57 @@ class OptionParser
     def <<: (String) -> untyped
   end
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - accept(*args, &blk)
+  # -->
   # See #accept.
   #
   def self.accept: (Class t, ?_Pattern pat) ?{ (*untyped) -> untyped } -> void
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - getopts(*args)
+  # -->
   # See #getopts.
   #
   def self.getopts: (*String options) -> Hash[String, untyped]
                   | (Array[String] args, *String options) -> Hash[String, untyped]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - inc(arg, default = nil)
+  # -->
   # Returns an incremented value of `default` according to `arg`.
   #
   def self.inc: (untyped arg, ?_ToI default) -> Integer?
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - reject(*args, &blk)
+  # -->
   # See #reject.
   #
   def self.reject: (Class t) -> void
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - terminate(arg = nil)
+  # -->
+  #
   def self.terminate: (?String arg) -> bot
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - top()
+  # -->
+  #
   def self.top: () -> OptionParser::List
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - with(*args, &block)
+  # -->
   # Initializes a new instance and evaluates the optional block in context of the
   # instance. Arguments `args` are passed to #new, see there for description of
   # parameters.
@@ -415,8 +453,17 @@ class OptionParser
 
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - abort(mesg = $!)
+  # -->
+  #
   def abort: (?_ToS mesg) -> bot
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - accept(*args, &blk)
+  # -->
   # Directs to accept specified class `t`. The argument string is passed to the
   # block in which it should be converted to the desired class.
   #
@@ -432,34 +479,68 @@ class OptionParser
 
   def add_officious: () -> void
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - additional_message(typ, opt)
+  # -->
   # Returns additional info.
   #
   def additional_message: (untyped typ, untyped opt) -> String?
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Heading banner preceding summary.
   #
   attr_accessor banner: String
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - base()
+  # -->
   # Subject of #on_tail.
   #
   def base: () -> List
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - candidate(word)
+  # -->
+  #
   def candidate: (String word) -> Array[untyped]
 
   def compsys: (untyped to, ?untyped name) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - def_head_option(*opts, &block)
+  # -->
+  #
   alias def_head_option define_head
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - def_option(*opts, &block)
+  # -->
+  #
   alias def_option define
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - def_tail_option(*opts, &block)
+  # -->
+  #
   alias def_tail_option define_tail
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Strings to be parsed in default.
   #
   attr_accessor default_argv: Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - define(*params, &block)
+  # -->
   # Creates an option from the given parameters `params`. See [Parameters for New
-  # Options](./option_params_rdoc.html).
+  # Options](./doc/optparse/option_params_rdoc.html).
   #
   # The block, if given, is the handler for the created option. When the option is
   # encountered during command-line parsing, the block is called with the argument
@@ -471,8 +552,12 @@ class OptionParser
             | (*String params, Proc | Method handler) -> untyped
             | (String params, Class | Array[String] | Hash[Symbol, untyped] | Regexp obj, ?String desc, Proc | Method handler) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - define_head(*params, &block)
+  # -->
   # Creates an option from the given parameters `params`. See [Parameters for New
-  # Options](./option_params_rdoc.html).
+  # Options](./doc/optparse/option_params_rdoc.html).
   #
   # The block, if given, is the handler for the created option. When the option is
   # encountered during command-line parsing, the block is called with the argument
@@ -484,8 +569,12 @@ class OptionParser
                  | (*String params, Proc | Method handler) -> untyped
                  | (String params, Class | Array[String] | Hash[Symbol, untyped] | Regexp obj, ?String desc, Proc | Method handler) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - define_tail(*params, &block)
+  # -->
   # Creates an option from the given parameters `params`. See [Parameters for New
-  # Options](./option_params_rdoc.html).
+  # Options](./doc/optparse/option_params_rdoc.html).
   #
   # The block, if given, is the handler for the created option. When the option is
   # encountered during command-line parsing, the block is called with the argument
@@ -497,6 +586,10 @@ class OptionParser
                  | (*String params, Proc | Method handler) -> untyped
                  | (String params, Class | Array[String] | Hash[Symbol, untyped] | Regexp obj, ?String desc, Proc | Method handler) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - environment(env = File.basename($0, '.*'))
+  # -->
   # Parses environment variable `env` or its uppercase with splitting like a
   # shell.
   #
@@ -504,6 +597,10 @@ class OptionParser
   #
   def environment: (?String env) -> Array[String]?
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - getopts(*args)
+  # -->
   # Wrapper method for getopts.rb.
   #
   #     params = ARGV.getopts("ab:", "foo", "bar:", "zot:Z;zot option")
@@ -514,14 +611,27 @@ class OptionParser
   #     # params["zot"] = "z"  # --zot Z
   #
   def getopts: (*String options) -> Hash[String, untyped]
-               | (Array[String] args, *String options) -> Hash[String, untyped]
+             | (Array[String] args, *String options) -> Hash[String, untyped]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - help()
+  # -->
   # Returns option summary string.
   #
   def help: () -> String
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - inc(*args)
+  # -->
+  #
   def inc: (*untyped args) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - load(filename = nil)
+  # -->
   # Loads options from file names as `filename`. Does nothing when the file is not
   # present. Returns whether successfully loaded.
   #
@@ -531,23 +641,35 @@ class OptionParser
   #
   def load: (?String filename) -> bool
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - make_switch(params, block = nil)
+  # -->
   # Creates an option from the given parameters `params`. See [Parameters for New
-  # Options](./option_params_rdoc.html).
+  # Options](./doc/optparse/option_params_rdoc.html).
   #
   # The block, if given, is the handler for the created option. When the option is
   # encountered during command-line parsing, the block is called with the argument
   # given for the option, if any. See [Option
   # Handlers](./option_params_rdoc.html#label-Option+Handlers).
   #
-  def make_switch: (Array[untyped] opts, ?Proc block) -> [untyped, untyped, untyped, untyped, untyped]
+  def make_switch: (Array[untyped] opts, ?Proc block) -> [ untyped, untyped, untyped, untyped, untyped ]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - new() { |self| ... }
+  # -->
   # Pushes a new List.
   #
   def new: () -> self
          | [T] () { (self) -> T } -> T
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - on(*params, &block)
+  # -->
   # Creates an option from the given parameters `params`. See [Parameters for New
-  # Options](./option_params_rdoc.html).
+  # Options](./doc/optparse/option_params_rdoc.html).
   #
   # The block, if given, is the handler for the created option. When the option is
   # encountered during command-line parsing, the block is called with the argument
@@ -559,9 +681,12 @@ class OptionParser
         | (*String params, Proc | Method handler) -> self
         | (String params, Class | Array[String] | Hash[Symbol, untyped] | Regexp obj, ?String desc, Proc | Method handler) -> self
 
-
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - on_head(*params, &block)
+  # -->
   # Creates an option from the given parameters `params`. See [Parameters for New
-  # Options](./option_params_rdoc.html).
+  # Options](./doc/optparse/option_params_rdoc.html).
   #
   # The block, if given, is the handler for the created option. When the option is
   # encountered during command-line parsing, the block is called with the argument
@@ -575,8 +700,12 @@ class OptionParser
              | (*String params, Proc | Method handler) -> self
              | (String params, Class | Array[String] | Hash[Symbol, untyped] | Regexp obj, ?String desc, Proc | Method handler) -> self
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - on_tail(*params, &block)
+  # -->
   # Creates an option from the given parameters `params`. See [Parameters for New
-  # Options](./option_params_rdoc.html).
+  # Options](./doc/optparse/option_params_rdoc.html).
   #
   # The block, if given, is the handler for the created option. When the option is
   # encountered during command-line parsing, the block is called with the argument
@@ -590,6 +719,10 @@ class OptionParser
              | (*String params, Proc | Method handler) -> self
              | (String params, Class | Array[String] | Hash[Symbol, untyped] | Regexp obj, ?String desc, Proc | Method handler) -> self
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - order(*argv, into: nil, &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
   # provided, the parsed option values are stored there via `[]=` method (so it
@@ -600,11 +733,19 @@ class OptionParser
   def order: (*String argv, ?into: _Intoable) ?{ (String) -> void } -> Array[String]
            | (Array[String] argv, ?into: _Intoable) ?{ (String) -> void } -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - order!(argv = default_argv, into: nil, &nonopt)
+  # -->
   # Same as #order, but removes switches destructively. Non-option arguments
   # remain in `argv`.
   #
   def order!: (?Array[String] argv, ?into: _Intoable) ?{ (String) -> void } -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse(*argv, into: nil)
+  # -->
   # Parses command line arguments `argv` in order when environment variable
   # POSIXLY_CORRECT is set, and in permutation mode otherwise. When optional
   # `into` keyword argument is provided, the parsed option values are stored there
@@ -613,11 +754,19 @@ class OptionParser
   def parse: (*String argv, ?into: _Intoable) -> Array[String]
            | (Array[String] argv, ?into: _Intoable) -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse!(argv = default_argv, into: nil)
+  # -->
   # Same as #parse, but removes switches destructively. Non-option arguments
   # remain in `argv`.
   #
   def parse!: (?Array[String] argv, ?into: _Intoable) -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - permute(*argv, into: nil)
+  # -->
   # Parses command line arguments `argv` in permutation mode and returns list of
   # non-option arguments. When optional `into` keyword argument is provided, the
   # parsed option values are stored there via `[]=` method (so it can be Hash, or
@@ -626,16 +775,25 @@ class OptionParser
   def permute: (*String argv, ?into: _Intoable) -> Array[String]
              | (Array[String] argv, ?into: _Intoable) -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - permute!(argv = default_argv, into: nil)
+  # -->
   # Same as #permute, but removes switches destructively. Non-option arguments
   # remain in `argv`.
   #
   def permute!: (?Array[String] argv, ?into: _Intoable) -> Array[String]
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Program name to be emitted in error message and default banner, defaults to
   # $0.
   #
   attr_accessor program_name: String
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - reject(*args, &blk)
+  # -->
   # Directs to reject specified class argument.
   #
   # `t`
@@ -646,21 +804,31 @@ class OptionParser
   #
   def reject: (Class t) -> void
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Release code
   #
   def release: () -> untyped
 
   def release=: (untyped) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - remove()
+  # -->
   # Removes the last List.
   #
   def remove: () -> List?
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Whether to require that options match exactly (disallows providing abbreviated
   # long option as short option).
   #
   attr_accessor require_exact: boolish
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - separator(string)
+  # -->
   # Add separator in summary.
   #
   def separator: (String string) -> void
@@ -674,14 +842,20 @@ class OptionParser
   #
   alias set_program_name program_name=
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Indentation for summary. Must be String (or have + String method).
   #
   alias set_summary_indent summary_indent=
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Width for option list portion of summary. Must be Numeric.
   #
   alias set_summary_width summary_width=
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk)
+  # -->
   # Puts option summary into `to` and returns `to`. Yields each line if a block is
   # given.
   #
@@ -694,44 +868,76 @@ class OptionParser
   # `indent`
   # :   Indentation, defaults to @summary_indent.
   #
-  #
   def summarize: (?_LtLtString to, ?Integer width, ?Integer max, ?String indent) ?{ (String line) -> void } -> _LtLtString
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Indentation for summary. Must be String (or have + String method).
   #
   attr_accessor summary_indent: String
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Width for option list portion of summary. Must be Numeric.
   #
   attr_accessor summary_width: Integer
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - terminate(arg = nil)
+  # -->
   # Terminates option parsing. Optional parameter `arg` is a string pushed back to
   # be the first non-option argument.
   #
   def terminate: (?String arg) -> bot
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - to_a()
+  # -->
   # Returns option summary list.
   #
   def to_a: () -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - to_s()
+  # -->
+  #
   alias to_s help
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - top()
+  # -->
   # Subject of #on / #on_head, #accept / #reject
   #
   def top: () -> List
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - ver()
+  # -->
   # Returns version string from program_name, version and release.
   #
   def ver: () -> String?
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Version
   #
   attr_accessor version: String?
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - warn(mesg = $!)
+  # -->
+  #
   def warn: (?_ToS mesg) -> void
 
   private
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - complete(typ, opt, icase = false, *pat)
+  # -->
   # Completes shortened long style option switch and returns pair of canonical
   # switch and switch descriptor OptionParser::Switch.
   #
@@ -744,9 +950,12 @@ class OptionParser
   # `pat`
   # :   Optional pattern for completion.
   #
-  #
   def complete: (untyped typ, untyped opt, ?untyped icase, *untyped pat) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - new(banner = nil, width = 32, indent = ' ' * 4) { |self| ... }
+  # -->
   # Initializes the instance and yields itself if called with a block.
   #
   # `banner`
@@ -756,9 +965,12 @@ class OptionParser
   # `indent`
   # :   Summary indent.
   #
-  #
   def initialize: (?String banner, ?Integer width, ?String indent) ?{ (OptionParser) -> void } -> void
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - notwice(obj, prv, msg)
+  # -->
   # Checks if an argument is given twice, in which case an ArgumentError is
   # raised. Called from OptionParser#switch only.
   #
@@ -769,15 +981,22 @@ class OptionParser
   # `msg`
   # :   Exception message.
   #
-  #
   def notwice: (untyped obj, untyped prv, untyped msg) -> untyped
 
   def parse_in_order: (?untyped argv, ?untyped setter) { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - search(id, key) { |k| ... }
+  # -->
   # Searches `key` in @stack for `id` hash and returns or yields the result.
   #
   def search: (untyped id, untyped key) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - visit(id, *args, &block)
+  # -->
   # Traverses @stack, sending each element method `id` with `args` and `block`.
   #
   def visit: (untyped id, *untyped args) { (*untyped) -> untyped } -> untyped
@@ -787,23 +1006,29 @@ OptionParser::ArgumentStyle: Hash[untyped, untyped]
 
 OptionParser::COMPSYS_HEADER: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Decimal integer format, to be converted to Integer.
+#
 OptionParser::DecimalInteger: Regexp
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Decimal integer/float number format, to be converted to Integer for integer
 # format, Float for float format.
+#
 OptionParser::DecimalNumeric: Regexp
 
 OptionParser::DefaultList: OptionParser::List
 
 OptionParser::NO_ARGUMENT: Symbol
 
-OptionParser::NoArgument: [:NONE, nil]
+OptionParser::NoArgument: [ :NONE, nil ]
 
 OptionParser::OPTIONAL_ARGUMENT: Symbol
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Ruby/C like octal/hexadecimal/binary integer format, to be converted to
 # Integer.
+#
 OptionParser::OctalInteger: Regexp
 
 OptionParser::Officious: Hash[untyped, untyped]
@@ -818,8 +1043,10 @@ OptionParser::SPLAT_PROC: Proc
 
 OptionParser::Version: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Acceptable argument classes. Now contains DecimalInteger, OctalInteger and
 # DecimalNumeric. See Acceptable argument classes (in source code).
+#
 module OptionParser::Acceptables
 end
 
@@ -829,26 +1056,40 @@ OptionParser::Acceptables::DecimalNumeric: Regexp
 
 OptionParser::Acceptables::OctalInteger: Regexp
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Raises when the given argument word can't be completed uniquely.
+#
 class OptionParser::AmbiguousArgument < OptionParser::InvalidArgument
 end
 
 OptionParser::AmbiguousArgument::Reason: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Raises when ambiguously completable string is encountered.
+#
 class OptionParser::AmbiguousOption < OptionParser::ParseError
 end
 
 OptionParser::AmbiguousOption::Reason: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Extends command line arguments array (ARGV) to parse itself.
+#
 module OptionParser::Arguable
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - extend_object(obj)
+  # -->
   # Initializes instance variable.
   #
   def self.extend_object: (untyped obj) -> untyped
 
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - getopts(*args)
+  # -->
   # Substitution of getopts is possible as follows. Also see OptionParser#getopts.
   #
   #     def getopts(*args)
@@ -860,6 +1101,10 @@ module OptionParser::Arguable
   #
   def getopts: (*String args) -> Hash[String, untyped]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - options() { |optparse| ... }
+  # -->
   # Actual OptionParser object, automatically created if nonexistent.
   #
   # If called with a block, yields the OptionParser object and returns the result
@@ -869,6 +1114,10 @@ module OptionParser::Arguable
   def options: () -> OptionParser
              | [T] () { (OptionParser) -> T } -> T?
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - options=(opt)
+  # -->
   # Sets OptionParser object, when `opt` is `false` or `nil`, methods
   # OptionParser::Arguable#options and OptionParser::Arguable#options= are
   # undefined. Thus, there is no ways to access the OptionParser object via the
@@ -876,73 +1125,132 @@ module OptionParser::Arguable
   #
   def options=: (OptionParser? opt) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - order!(&blk)
+  # -->
   # Parses `self` destructively in order and returns `self` containing the rest
   # arguments left unparsed.
   #
   def order!: () ?{ (String) -> void } -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse!()
+  # -->
   # Parses `self` destructively and returns `self` containing the rest arguments
   # left unparsed.
   #
   def parse!: () -> Array[String]
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - permute!()
+  # -->
   # Parses `self` destructively in permutation mode and returns `self` containing
   # the rest arguments left unparsed.
   #
   def permute!: () -> Array[String]
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Hash with completion search feature. See OptionParser::Completion.
+#
 class OptionParser::CompletingHash < Hash[untyped, untyped]
   include OptionParser::Completion
 
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - match(key)
+  # -->
   # Completion for hash key.
   #
   def match: (untyped key) -> untyped
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Keyword completion module.  This allows partial arguments to be specified and
 # resolved against a list of acceptable values.
+#
 module OptionParser::Completion
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - candidate(key, icase = false, pat = nil, &block)
+  # -->
+  #
   def self.candidate: (untyped key, ?untyped icase, ?untyped pat) { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - regexp(key, icase)
+  # -->
+  #
   def self.regexp: (untyped key, untyped icase) -> untyped
 
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - candidate(key, icase = false, pat = nil)
+  # -->
+  #
   def candidate: (untyped key, ?untyped icase, ?untyped pat) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - complete(key, icase = false, pat = nil) { |key, *sw| ... }
+  # -->
+  #
   def complete: (untyped key, ?untyped icase, ?untyped pat) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - convert(opt = nil, val = nil, *)
+  # -->
+  #
   def convert: (?untyped opt, ?untyped val, *untyped) -> untyped
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Raises when the given argument does not match required format.
+#
 class OptionParser::InvalidArgument < OptionParser::ParseError
 end
 
 OptionParser::InvalidArgument::Reason: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Raises when switch is undefined.
+#
 class OptionParser::InvalidOption < OptionParser::ParseError
 end
 
 OptionParser::InvalidOption::Reason: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Simple option list providing mapping from short and/or long option string to
 # OptionParser::Switch and mapping from acceptable argument to matching pattern
 # and converter pair. Also provides summary feature.
+#
 class OptionParser::List
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - accept(t, pat = /.*/m, &block)
+  # -->
   # See OptionParser.accept.
   #
   def accept: (untyped t, ?untyped pat) { (*untyped) -> untyped } -> untyped
 
   def add_banner: (untyped to) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - append(*args)
+  # -->
   # Appends `switch` at the tail of the list, and associates short, long and
   # negated long options. Arguments are:
   #
@@ -960,10 +1268,15 @@ class OptionParser::List
   #
   def append: (*untyped args) -> untyped
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Map from acceptable argument types to pattern and converter pairs.
   #
   def atype: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - complete(id, opt, icase = false, *pat, &block)
+  # -->
   # Searches list `id` for `opt` and the optional patterns for completion `pat`.
   # If `icase` is true, the search is case insensitive. The result is returned or
   # yielded if a block is given. If it isn't found, nil is returned.
@@ -972,20 +1285,35 @@ class OptionParser::List
 
   def compsys: (*untyped args) { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - each_option(&block)
+  # -->
   # Iterates over each option, passing the option to the `block`.
   #
   def each_option: () { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - get_candidates(id) { |__send__(id).keys| ... }
+  # -->
+  #
   def get_candidates: (untyped id) -> untyped
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # List of all switches and summary string.
   #
   def list: () -> untyped
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Map from long style option switches to actual switch objects.
   #
   def long: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - prepend(*args)
+  # -->
   # Inserts `switch` at the head of the list, and associates short, long and
   # negated long options. Arguments are:
   #
@@ -1003,19 +1331,32 @@ class OptionParser::List
   #
   def prepend: (*untyped args) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - reject(t)
+  # -->
   # See OptionParser.reject.
   #
   def reject: (untyped t) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - search(id, key) { |val| ... }
+  # -->
   # Searches `key` in `id` list. The result is returned or yielded if a block is
   # given. If it isn't found, nil is returned.
   #
   def search: (untyped id, untyped key) -> untyped
 
+  # <!-- rdoc-file=lib/optparse.rb -->
   # Map from short style option switches to actual switch objects.
   #
   def short: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - summarize(*args, &block)
+  # -->
   # Creates the summary table, passing each line to the `block` (without newline).
   # The arguments `args` are passed along to the summarize method which is called
   # on every option.
@@ -1024,10 +1365,18 @@ class OptionParser::List
 
   private
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - new()
+  # -->
   # Just initializes all instance variables.
   #
   def initialize: () -> void
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - update(sw, sopts, lopts, nsw = nil, nlopts = nil)
+  # -->
   # Adds `sw` according to `sopts`, `lopts` and `nlopts`.
   #
   # `sw`
@@ -1039,29 +1388,41 @@ class OptionParser::List
   # `nlopts`
   # :   Negated long style options list.
   #
-  #
   def update: (untyped sw, untyped sopts, untyped lopts, ?untyped nsw, ?untyped nlopts) -> untyped
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Raises when a switch with mandatory argument has no argument.
+#
 class OptionParser::MissingArgument < OptionParser::ParseError
 end
 
 OptionParser::MissingArgument::Reason: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Raises when there is an argument for a switch which takes no argument.
+#
 class OptionParser::NeedlessArgument < OptionParser::ParseError
 end
 
 OptionParser::NeedlessArgument::Reason: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Map from option/keyword string to object with completion.
+#
 class OptionParser::OptionMap < Hash[untyped, untyped]
   include OptionParser::Completion
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Base class of exceptions from OptionParser.
+#
 class OptionParser::ParseError < RuntimeError
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - filter_backtrace(array)
+  # -->
+  #
   def self.filter_backtrace: (untyped array) -> untyped
 
   public
@@ -1072,46 +1433,99 @@ class OptionParser::ParseError < RuntimeError
 
   def args: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - inspect()
+  # -->
+  #
   def inspect: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - message()
+  # -->
   # Default stringizing method to emit standard error message.
   #
   def message: () -> String
 
+  # <!-- rdoc-file=lib/optparse.rb -->
+  #
   def reason: () -> untyped
 
   def reason=: (untyped) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - recover(argv)
+  # -->
   # Pushes back erred argument(s) to `argv`.
   #
   def recover: (untyped argv) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - set_backtrace(array)
+  # -->
+  #
   def set_backtrace: (untyped array) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - set_option(opt, eq)
+  # -->
+  #
   def set_option: (untyped opt, untyped eq) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - to_s()
+  # -->
+  #
   alias to_s message
 
   private
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - new(*args, additional: nil)
+  # -->
+  #
   def initialize: (*untyped args, ?additional: untyped) -> void
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Reason which caused the error.
+#
 OptionParser::ParseError::Reason: String
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Individual switch class.  Not important to the user.
 #
 # Defined within Switch are several Switch-derived classes: NoArgument,
 # RequiredArgument, etc.
+#
 class OptionParser::Switch
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - guess(arg)
+  # -->
   # Guesses argument style from `arg`.  Returns corresponding OptionParser::Switch
   # class (OptionalArgument, etc.).
   #
   def self.guess: (untyped arg) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - incompatible_argument_styles(arg, t)
+  # -->
+  #
   def self.incompatible_argument_styles: (untyped arg, untyped t) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - pattern()
+  # -->
+  #
   def self.pattern: () -> untyped
 
   public
@@ -1136,6 +1550,10 @@ class OptionParser::Switch
 
   def short: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - summarize(sdone = {}, ldone = {}, width = 1, max = width - 1, indent = "") { |indent| ... }
+  # -->
   # Produces the summary text. Each line of the summary is yielded to the block
   # (without newline).
   #
@@ -1151,63 +1569,113 @@ class OptionParser::Switch
   # `indent`
   # :   Prefix string indents all summarized lines.
   #
-  #
   def summarize: (?untyped sdone, ?untyped ldone, ?untyped width, ?untyped max, ?untyped indent) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - switch_name()
+  # -->
   # Main name of the switch.
   #
   def switch_name: () -> untyped
 
   private
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - conv_arg(arg, val = [])
+  # -->
   # Parses argument, converts and returns `arg`, `block` and result of conversion.
   # Yields at semi-error condition instead of raising an exception.
   #
   def conv_arg: (untyped arg, ?untyped val) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - new(pattern = nil, conv = nil, short = nil, long = nil, arg = nil, desc = ([] if short or long), block = nil, &_block)
+  # -->
+  #
   def initialize: (?untyped pattern, ?untyped conv, ?untyped short, ?untyped long, ?untyped arg, ?untyped desc, ?untyped block) { (*untyped) -> untyped } -> void
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse_arg(arg) { |InvalidArgument, arg| ... }
+  # -->
   # Parses `arg` and returns rest of `arg` and matched portion to the argument
   # pattern. Yields when the pattern doesn't match substring.
   #
   def parse_arg: (untyped arg) -> untyped
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Switch that takes no arguments.
+#
 class OptionParser::Switch::NoArgument < OptionParser::Switch
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - incompatible_argument_styles(*)
+  # -->
+  #
   def self.incompatible_argument_styles: (*untyped) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - pattern()
+  # -->
+  #
   def self.pattern: () -> untyped
 
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse(arg, argv) { |NeedlessArgument, arg| ... }
+  # -->
   # Raises an exception if any arguments given.
   #
   def parse: (untyped arg, untyped argv) -> untyped
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Switch that can omit argument.
+#
 class OptionParser::Switch::OptionalArgument < OptionParser::Switch
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse(arg, argv, &error)
+  # -->
   # Parses argument if given, or uses default value.
   #
   def parse: (untyped arg, untyped argv) { (*untyped) -> untyped } -> untyped
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Switch that takes an argument, which does not begin with '-'.
+#
 class OptionParser::Switch::PlacedArgument < OptionParser::Switch
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse(arg, argv, &error)
+  # -->
   # Returns nil if argument is not present or begins with '-'.
   #
   def parse: (untyped arg, untyped argv) { (*untyped) -> untyped } -> untyped
 end
 
+# <!-- rdoc-file=lib/optparse.rb -->
 # Switch that takes an argument.
+#
 class OptionParser::Switch::RequiredArgument < OptionParser::Switch
   public
 
+  # <!--
+  #   rdoc-file=lib/optparse.rb
+  #   - parse(arg, argv)
+  # -->
   # Raises an exception if argument is not present.
   #
   def parse: (untyped arg, untyped argv) -> untyped