https://git.ruby-lang.org/ruby.git/commit/?id=a5ecce9187

From a5ecce9187a275497895eca3fdb080ca60297931 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@y...>
Date: Wed, 7 Apr 2021 11:58:46 -0500
Subject: [ruby/optparse] Make use of option_params.rdoc

https://github.com/ruby/optparse/commit/d55d9284c3
---
 doc/creates_option.rdoc              |  7 +++
 doc/option_params/option_params.rdoc |  4 +-
 lib/optparse.rb                      | 82 ++++++++----------------------------
 lib/optparse/kwargs.rb               |  2 +
 4 files changed, 28 insertions(+), 67 deletions(-)
 create mode 100644 doc/creates_option.rdoc

diff --git a/doc/creates_option.rdoc b/doc/creates_option.rdoc
new file mode 100644
index 0000000..d006706
--- /dev/null
+++ b/doc/creates_option.rdoc
@@ -0,0 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/doc/creates_option.rdoc#L1
+Creates an option from the given parameters +params+.
+See {Parameters for New Options}[doc/option_params/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}[doc/option_params/option_params_rdoc.html#label-Option+Handlers].
diff --git a/doc/option_params/option_params.rdoc b/doc/option_params/option_params.rdoc
index 7cf5ef8..ebd08f1 100644
--- a/doc/option_params/option_params.rdoc
+++ b/doc/option_params/option_params.rdoc
@@ -55,7 +55,7 @@ Contents: https://github.com/ruby/ruby/blob/trunk/doc/option_params/option_params.rdoc#L55
   - {Array}[#label-Array]
   - {Regexp}[#label-Regexp]
 - {Descriptions}[#label-Descriptions]
-- {Handlers}[#label-Handlers]
+- {Option Handlers}[#label-Option+Handlers]
   - {Handler Blocks}[#label-Handler+Blocks]
   - {Handler Procs}[#label-Handler+Procs]
   - {Handler Methods}[#label-Handler+Methods]
@@ -759,7 +759,7 @@ Executions: https://github.com/ruby/ruby/blob/trunk/doc/option_params/option_params.rdoc#L759
   $ ruby descriptions.rb --xxx
   ["--xxx", true]
 
-=== Handlers
+=== Option Handlers
 
 The handler for an option is an executable that will be called
 when the option is encountered.  The handler may be:
diff --git a/lib/optparse.rb b/lib/optparse.rb
index 598ebd1..0f92eba8 100644
--- a/lib/optparse.rb
+++ b/lib/optparse.rb
@@ -240,14 +240,14 @@ https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L240
 #
 #   require 'optparse'
 #
-#   params = {}
+#   options = {}
 #   OptionParser.new do |parser|
 #     parser.on('-a')
 #     parser.on('-b NUM', Integer)
 #     parser.on('-v', '--verbose')
-#   end.parse!(into: params)
+#   end.parse!(into: options)
 #
-#   p params
+#   p options
 #
 # Used:
 #
@@ -1314,64 +1314,7 @@ XXX https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L1314
   # :call-seq:
   #   make_switch(params, block = nil)
   #
-  # Creates an OptionParser::Switch from the parameters. The parsed argument
-  # value is passed to the given block, where it can be processed.
-  #
-  # See at the beginning of OptionParser for some full examples.
-  #
-  # +params+ can include the following elements:
-  #
-  # [Argument style:]
-  #   One of the following:
-  #     :NONE, :REQUIRED, :OPTIONAL
-  #
-  # [Argument pattern:]
-  #   Acceptable option argument format, must be pre-defined with
-  #   OptionParser.accept or OptionParser#accept, or Regexp. This can appear
-  #   once or assigned as String if not present, otherwise causes an
-  #   ArgumentError. Examples:
-  #     Float, Time, Array
-  #
-  # [Possible argument values:]
-  #   Hash or Array.
-  #     [:text, :binary, :auto]
-  #     %w[iso-2022-jp shift_jis euc-jp utf8 binary]
-  #     { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
-  #
-  # [Long style switch:]
-  #   Specifies a long style switch which takes a mandatory, optional or no
-  #   argument. It's a string of the following form:
-  #     "--switch=MANDATORY" or "--switch MANDATORY"
-  #     "--switch[=OPTIONAL]"
-  #     "--switch"
-  #
-  # [Short style switch:]
-  #   Specifies short style switch which takes a mandatory, optional or no
-  #   argument. It's a string of the following form:
-  #     "-xMANDATORY"
-  #     "-x[OPTIONAL]"
-  #     "-x"
-  #   There is also a special form which matches character range (not full
-  #   set of regular expression):
-  #     "-[a-z]MANDATORY"
-  #     "-[a-z][OPTIONAL]"
-  #     "-[a-z]"
-  #
-  # [Argument style and description:]
-  #   Instead of specifying mandatory or optional arguments directly in the
-  #   switch parameter, this separate parameter can be used.
-  #     "=MANDATORY"
-  #     "=[OPTIONAL]"
-  #
-  # [Description:]
-  #   Description string for the option.
-  #     "Run verbosely"
-  #   If you give multiple description strings, each string will be printed
-  #   line by line.
-  #
-  # [Handler:]
-  #   Handler for the parsed argument value. Either give a block or pass a
-  #   Proc or Method as an argument.
+  # :include: ../doc/creates_option.rdoc
   #
   def make_switch(opts, block = nil)
     short, long, nolong, style, pattern, conv, not_pattern, not_conv, not_style = [], [], []
@@ -1509,6 +1452,8 @@ XXX https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L1452
   # :call-seq:
   #   define(*params, &block)
   #
+  # :include: ../doc/creates_option.rdoc
+  #
   def define(*opts, &block)
     top.append(*(sw = make_switch(opts, block)))
     sw[0]
@@ -1517,8 +1462,7 @@ XXX https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L1462
   # :call-seq:
   #   on(*params, &block)
   #
-  # Add option switch and handler. See #make_switch for an explanation of
-  # parameters.
+  # :include: ../doc/creates_option.rdoc
   #
   def on(*opts, &block)
     define(*opts, &block)
@@ -1529,6 +1473,8 @@ XXX https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L1473
   # :call-seq:
   #   define_head(*params, &block)
   #
+  # :include: ../doc/creates_option.rdoc
+  #
   def define_head(*opts, &block)
     top.prepend(*(sw = make_switch(opts, block)))
     sw[0]
@@ -1537,7 +1483,9 @@ XXX https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L1483
   # :call-seq:
   #   on_head(*params, &block)
   #
-  # Add option switch like with #on, but at head of summary.
+  # :include: ../doc/creates_option.rdoc
+  #
+  # The new option is added at the head of the summary.
   #
   def on_head(*opts, &block)
     define_head(*opts, &block)
@@ -1548,6 +1496,8 @@ XXX https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L1496
   # :call-seq:
   #   define_tail(*params, &block)
   #
+  # :include: ../doc/creates_option.rdoc
+  #
   def define_tail(*opts, &block)
     base.append(*(sw = make_switch(opts, block)))
     sw[0]
@@ -1557,7 +1507,9 @@ XXX https://github.com/ruby/ruby/blob/trunk/lib/optparse.rb#L1507
   # :call-seq:
   #   on_tail(*params, &block)
   #
-  # Add option switch like with #on, but at tail of summary.
+  # :include: ../doc/creates_option.rdoc
+  #
+  # The new option is added at the tail of the summary.
   #
   def on_tail(*opts, &block)
     define_tail(*opts, &block)
diff --git a/lib/optparse/kwargs.rb b/lib/optparse/kwargs.rb
index 5a2def4..d858faf 100644
--- a/lib/optparse/kwargs.rb
+++ b/lib/optparse/kwargs.rb
@@ -5,6 +5,8 @@ class OptionParser https://github.com/ruby/ruby/blob/trunk/lib/optparse/kwargs.rb#L5
   # :call-seq:
   #   define_by_keywords(options, method, **params)
   #
+  # :include: ../../doc/creates_option.rdoc
+  #
   def define_by_keywords(options, meth, **opts)
     meth.parameters.each do |type, name|
       case type
-- 
cgit v1.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/