diff --git a/lib/optparse.rb b/lib/optparse.rb
index 08abca220f14e2..51dbfd0ad2190e 100644
--- a/lib/optparse.rb
+++ b/lib/optparse.rb
@@ -1216,9 +1216,9 @@ def self.accept(*args, &blk) top.accept(*args, &blk) end
   #
   # Directs to reject specified class argument.
   #
-  # +t+:: Argument class specifier, any object including Class.
+  # +type+:: Argument class specifier, any object including Class.
   #
-  #   reject(t)
+  #   reject(type)
   #
   def reject(*args, &blk) top.reject(*args, &blk) end
   #
@@ -1347,6 +1347,9 @@ def base
   #
   # Pushes a new List.
   #
+  # If a block is given, yields +self+ and returns the result of the
+  # block, otherwise returns +self+.
+  #
   def new
     @stack.push(List.new)
     if block_given?
@@ -1570,6 +1573,12 @@ def make_switch(opts, block = nil)
       nolong
   end
 
+  # ----
+  # Option definition phase methods
+  #
+  # These methods are used to define options, or to construct an
+  # OptionParser instance in other words.
+
   # :call-seq:
   #   define(*params, &block)
   #
@@ -1645,6 +1654,13 @@ def separator(string)
     top.append(string, nil, nil)
   end
 
+  # ----
+  # Arguments parse phase methods
+  #
+  # These methods parse +argv+, convert, and store the results by
+  # calling handlers.  As these methods do not modify +self+, +self+
+  # can be frozen.
+
   #
   # Parses command line arguments +argv+ in order. When a block is given,
   # each non-option argument is yielded. When optional +into+ keyword