$NetBSD: patch-cm,v 1.2.2.2 2006/07/31 22:43:13 salo Exp $

--- lib/optparse.rb.orig	2005-11-22 23:53:16.000000000 +0900
+++ lib/optparse.rb
@@ -306,15 +306,8 @@ class OptionParser
     end
 
     #
-    # OptionParser::Switch#parse_arg(arg) {non-serious error handler}
-    #
-    # Parses argument and returns rest of ((|arg|)), and matched portion
-    # to the argument pattern.
-    #  :Parameters:
-    #    : ((|arg|))
-    #      option argument to be parsed.
-    #    : (({block}))
-    #      yields when the pattern doesn't match sub-string.
+    # 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(arg)
       pattern or return nil, arg
@@ -337,20 +330,9 @@ class OptionParser
     private :parse_arg
 
     #
-    # OptionParser::Switch#conv_arg(arg, val) {semi-error handler}
-    #
-    # Parses argument, convert and returns ((|arg|)), ((|block|)) and
-    # result of conversion.
-    #  : Arguments to ((|@conv|))
-    #    substrings matched to ((|@pattern|)), ((|$&|)), ((|$1|)),
-    #    ((|$2|)) and so on.
-    #  :Parameters:
-    #    : ((|arg|))
-    #      argument string follows the switch.
-    #    : ((|val|))
-    #      following argument.
-    #    : (({block}))
-    #      (({yields})) at semi-error condition, instead of raises exception.
+    # Parses argument, converts and returns +arg+, +block+ and result of
+    # conversion. Yields at semi-error condition instead of raising an
+    # exception.
     #
     def conv_arg(arg, val = nil)
       if block
@@ -367,23 +349,16 @@ class OptionParser
     private :conv_arg
 
     #
-    # OptionParser::Switch#summarize(sdone, ldone, width, max, indent)
+    # Produces the summary text. Each line of the summary is yielded to the
+    # block (without newline).
     #
-    # Makes summary strings.
-    #  :Parameters:
-    #    : ((|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 word, right side,
-    #      description part strings start at ((|width|)) column.
-    #    : ((|max|))
-    #      maximum width of left side, options are filled within ((|max|)) columns.
-    #    : ((|indent|))
-    #      prefix string indents each summarized lines.
-    #    : (({block}))
-    #      to be passed each lines(without newline).
+    # +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.
     #
     def summarize(sdone = [], ldone = [], width = 1, max = width - 1, indent = "")
       sopts, lopts, s = [], [], nil
@@ -541,19 +516,12 @@ class OptionParser
     end
 
     #
-    # OptionParser::List#update(sw, sopts, lopts, nlopts = nil)
+    # Adds +sw+ according to +sopts+, +lopts+ and +nlopts+.
     #
-    # Adds ((|sw|)) according to ((|sopts|)), ((|lopts|)) and
-    # ((|nlopts|)).
-    #  :Parameters:
-    #    : ((|sw|))
-    #      ((<OptionParser::Switch>)) instance to be added.
-    #    : ((|sopts|))
-    #      short style options list.
-    #    : ((|lopts|))
-    #      long style options list.
-    #    : ((|nlopts|))
-    #      negated long style options list.
+    # +sw+::     OptionParser::Switch instance to be added.
+    # +sopts+::  Short style option list.
+    # +lopts+::  Long style option list.
+    # +nlopts+:: Negated long style options list.
     #
     def update(sw, sopts, lopts, nsw = nil, nlopts = nil)
       o = nil
@@ -566,45 +534,40 @@ class OptionParser
     private :update
 
     #
-    # OptionParser::List#prepend(switch, short_opts, long_opts, nolong_opts)
+    # Inserts +switch+ at the head of the list, and associates short, long
+    # and negated long options. Arguments are:
+    # 
+    # +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.
+    #
+    #   prepend(switch, short_opts, long_opts, nolong_opts)
     #
-    # Inserts ((|switch|)) at head of the list, and associates short,
-    # long and negated long options.
     def prepend(*args)
       update(*args)
       @list.unshift(args[0])
     end
 
     #
-    # OptionParser::List#append(switch, short_opts, long_opts, nolong_opts)
+    # Appends +switch+ at the tail of the list, and associates short, long
+    # and negated long options. Arguments are:
+    # 
+    # +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.
+    #
+    #   append(switch, short_opts, long_opts, nolong_opts)
     #
-    # Appends ((|switch|)) at tail of the list, and associates short,
-    # long and negated long options.
-    #  :Parameters:
-    #    : ((|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.
     def append(*args)
       update(*args)
       @list.push(args[0])
     end
 
     #
-    # OptionParser::List#search(id, key) [{block}]
-    #
-    # Searches ((|key|)) in ((|id|)) list.
-    #  :Parameters:
-    #    : ((|id|))
-    #      searching list.
-    #    : ((|k|))
-    #      searching key.
-    #    : (({block}))
-    #      yielded with the found value when succeeded.
+    # 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(id, key)
       if list = __send__(id)
@@ -615,35 +578,19 @@ class OptionParser
     end
 
     #
-    # OptionParser::List#complete(id, opt, *pat, &block)
-    #
-    # Searches list ((|id|)) for ((|opt|)) and ((|*pat|)).
-    #  :Parameters:
-    #    : ((|id|))
-    #      searching list.
-    #    : ((|opt|))
-    #      searching key.
-    #    : ((|icase|))
-    #      search case insensitive if true.
-    #    : ((|*pat|))
-    #      optional pattern for completion.
-    #    : (({block}))
-    #      yielded with the found value when succeeded.
+    # 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.
     #
     def complete(id, opt, icase = false, *pat, &block)
       __send__(id).complete(opt, icase, *pat, &block)
     end
 
     #
-    # OptionParser::List#summarize(*args) {...}
-    #
-    # Making summary table, yields the (({block})) with each lines.
-    # Each elements of (({@list})) should be able to (({summarize})).
-    #  :Parameters:
-    #    : ((|args|))
-    #      passed to elements#summarize through.
-    #    : (({block}))
-    #      to be passed each lines(without newline).
+    # 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.
     #
     def summarize(*args, &block)
       list.each do |opt|
@@ -815,8 +762,7 @@ class OptionParser
     yield self if block_given?
   end
 
-  # :nodoc:
-  def add_officious
+  def add_officious  # :nodoc:
     list = base()
     Officious.each_pair do |opt, block|
       list.long[opt] ||= block.call(self)
