From bbccabe6d67c83ed81028e4c5ca9daaa4f6f7531 Mon Sep 17 00:00:00 2001
From: Nobuyoshi Nakada <nobu@ruby-lang.org>
Date: Mon, 12 Feb 2024 01:07:05 +0900
Subject: [PATCH] [ruby/optparse] [DOC] Add missing documents

https://github.com/ruby/optparse/commit/33956ce93f
---
 lib/optparse.rb         | 34 ++++++++++++++++++++++++++++++----
 lib/optparse/ac.rb      | 16 ++++++++++++++++
 lib/optparse/version.rb |  9 +++++++++
 3 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/lib/optparse.rb b/lib/optparse.rb
index 8382364977..438a09fbf6 100644
--- a/lib/optparse.rb
+++ b/lib/optparse.rb
@@ -8,7 +8,6 @@
 # See OptionParser for documentation.
 #
 
-
 #--
 # == Developer Documentation (not for RDoc output)
 #
@@ -425,6 +424,7 @@
 # If you have any questions, file a ticket at http://bugs.ruby-lang.org.
 #
 class OptionParser
+  # The version string
   OptionParser::Version = "0.4.0"
 
   # :stopdoc:
@@ -438,6 +438,8 @@ class OptionParser
   # and resolved against a list of acceptable values.
   #
   module Completion
+    # :nodoc:
+
     def self.regexp(key, icase)
       Regexp.new('\A' + Regexp.quote(key).gsub(/\w+\b/, '\&\w*'), icase)
     end
@@ -510,6 +512,8 @@ class OptionParser
   # RequiredArgument, etc.
   #
   class Switch
+    # :nodoc:
+
     attr_reader :pattern, :conv, :short, :long, :arg, :desc, :block
 
     #
@@ -715,10 +719,10 @@ class OptionParser
         conv_arg(arg)
       end
 
-      def self.incompatible_argument_styles(*)
+      def self.incompatible_argument_styles(*) # :nodoc:
       end
 
-      def self.pattern
+      def self.pattern          # :nodoc:
         Object
       end
 
@@ -804,6 +808,8 @@ class OptionParser
   # matching pattern and converter pair. Also provides summary feature.
   #
   class List
+    # :nodoc:
+
     # Map from acceptable argument types to pattern and converter pairs.
     attr_reader :atype
 
@@ -1185,6 +1191,11 @@ XXX
   end
 
   @stack = [DefaultList]
+  #
+  # Returns the global top option list.
+  #
+  # Do not use directly.
+  #
   def self.top() DefaultList end
 
   #
@@ -1297,10 +1308,24 @@ XXX
     end
   end
 
+  #
+  # Shows warning message with the program name
+  #
+  # +mesg+:: Message, defaulted to +$!+.
+  #
+  # See Kernel#warn.
+  #
   def warn(mesg = $!)
     super("#{program_name}: #{mesg}")
   end
 
+  #
+  # Shows message with the program name then aborts.
+  #
+  # +mesg+:: Message, defaulted to +$!+.
+  #
+  # See Kernel#abort.
+  #
   def abort(mesg = $!)
     super("#{program_name}: #{mesg}")
   end
@@ -2342,7 +2367,8 @@ XXX
       super
       obj.instance_eval {@optparse = nil}
     end
-    def initialize(*args)
+
+    def initialize(*args)       # :nodoc:
       super
       @optparse = nil
     end
diff --git a/lib/optparse/ac.rb b/lib/optparse/ac.rb
index 0953725e46..23fc740d10 100644
--- a/lib/optparse/ac.rb
+++ b/lib/optparse/ac.rb
@@ -1,7 +1,11 @@
 # frozen_string_literal: false
 require_relative '../optparse'
 
+#
+# autoconf-like options.
+#
 class OptionParser::AC < OptionParser
+  # :stopdoc:
   private
 
   def _check_ac_args(name, block)
@@ -14,6 +18,7 @@ class OptionParser::AC < OptionParser
   end
 
   ARG_CONV = proc {|val| val.nil? ? true : val}
+  private_constant :ARG_CONV
 
   def _ac_arg_enable(prefix, name, help_string, block)
     _check_ac_args(name, block)
@@ -29,16 +34,27 @@ class OptionParser::AC < OptionParser
     enable
   end
 
+  # :startdoc:
+
   public
 
+  # Define <tt>--enable</tt> / <tt>--disable</tt> style option
+  #
+  # Appears as <tt>--enable-<i>name</i></tt> in help message.
   def ac_arg_enable(name, help_string, &block)
     _ac_arg_enable("enable", name, help_string, block)
   end
 
+  # Define <tt>--enable</tt> / <tt>--disable</tt> style option
+  #
+  # Appears as <tt>--disable-<i>name</i></tt> in help message.
   def ac_arg_disable(name, help_string, &block)
     _ac_arg_enable("disable", name, help_string, block)
   end
 
+  # Define <tt>--with</tt> / <tt>--without</tt> style option
+  #
+  # Appears as <tt>--with-<i>name</i></tt> in help message.
   def ac_arg_with(name, help_string, &block)
     _check_ac_args(name, block)
 
diff --git a/lib/optparse/version.rb b/lib/optparse/version.rb
index b869d8fe51..b5ed695146 100644
--- a/lib/optparse/version.rb
+++ b/lib/optparse/version.rb
@@ -2,6 +2,11 @@
 # OptionParser internal utility
 
 class << OptionParser
+  #
+  # Shows version string in packages if Version is defined.
+  #
+  # +pkgs+:: package list
+  #
   def show_version(*pkgs)
     progname = ARGV.options.program_name
     result = false
@@ -47,6 +52,8 @@ class << OptionParser
     result
   end
 
+  # :stopdoc:
+
   def each_const(path, base = ::Object)
     path.split(/::|\//).inject(base) do |klass, name|
       raise NameError, path unless Module === klass
@@ -68,4 +75,6 @@ class << OptionParser
       end
     end
   end
+
+  # :startdoc:
 end