Convert RDoc to OptionParser, clean up -h output, namespace Options under RDoc.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@14927 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 84 insertions, 81 deletions

diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb
index ca8c5d02a2..b1359511bf 100644
--- a/lib/rdoc/rdoc.rb
+++ b/lib/rdoc/rdoc.rb
@@ -1,15 +1,8 @@
-# See README.
-#
- 
-
-VERSION_STRING = %{RDoc V1.0.1 - 20041108}
-
-
 require 'rdoc/parsers/parse_rb.rb'
 require 'rdoc/parsers/parse_c.rb'
 require 'rdoc/parsers/parse_f95.rb'
-
 require 'rdoc/parsers/parse_simple.rb'
+
 require 'rdoc/options'
 
 require 'rdoc/diagram'
@@ -18,19 +11,25 @@ require 'find'
 require 'fileutils'
 require 'time'
 
-# We put rdoc stuff in the RDoc module to avoid namespace clutter.
-#
-# ToDo: This isn't universally true.
-#
+##
 # :include: README
 
 module RDoc
 
-  # Name of the dotfile that contains the description of files to be
-  # processed in the current directory
+  ##
+  # RDoc version you are using
+
+  VERSION = "2.0.0"
+
+  ##
+  # Name of the dotfile that contains the description of files to be processed
+  # in the current directory
+
   DOT_DOC_FILENAME = ".document"
 
+  ##
   # Simple stats collector
+
   class Stats
     attr_accessor :num_files, :num_classes, :num_modules, :num_methods
     def initialize
@@ -46,13 +45,14 @@ module RDoc
     end
   end
 
+  ##
+  # Exception thrown by any rdoc error.
 
-  # Exception thrown by any rdoc error. Only the #message part is
-  # of use externally.
+  class Error < StandardError; end
 
-  class RDocError < Exception
-  end
+  RDocError = Error # :nodoc:
 
+  ##
   # Encapsulate the production of rdoc documentation. Basically
   # you can use this as you would invoke rdoc from the command
   # line:
@@ -61,24 +61,25 @@ module RDoc
   #    rdoc.document(args)
   #
   # where _args_ is an array of strings, each corresponding to
-  # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb 
+  # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb
   # for details.
-  
+
   class RDoc
 
+    Generator = Struct.new(:file_name, :class_name, :key)
+
     ##
     # This is the list of output generators that we
     # support
-    
-    Generator = Struct.new(:file_name, :class_name, :key)
-    
+
     GENERATORS = {}
-    $:.collect {|d|
-      File::expand_path(d)
-    }.find_all {|d|
-      File::directory?("#{d}/rdoc/generators")
-    }.each {|dir|
-      Dir::entries("#{dir}/rdoc/generators").each {|gen|
+
+    $LOAD_PATH.collect do |d|
+      File.expand_path d
+    end.find_all do |d|
+      File.directory? "#{d}/rdoc/generators"
+    end.each do |dir|
+      Dir.entries("#{dir}/rdoc/generators").each do |gen|
         next unless /(\w+)_generator.rb$/ =~ gen
         type = $1
         unless GENERATORS.has_key? type
@@ -86,31 +87,28 @@ module RDoc
                                            "#{type.upcase}Generator".intern,
                                            type)
         end
-      }
-    }                                                    
+      end
+    end
 
-    #######
     private
-    #######
 
     ##
     # Report an error message and exit
-    
+
     def error(msg)
-      raise RDocError.new(msg)
+      raise RDoc::Error, msg
     end
-    
+
     ##
-    # Create an output dir if it doesn't exist. If it does
-    # exist, but doesn't contain the flag file <tt>created.rid</tt>
-    # then we refuse to use it, as we may clobber some
-    # manually generated documentation
-    
+    # Create an output dir if it doesn't exist. If it does exist, but doesn't
+    # contain the flag file <tt>created.rid</tt> then we refuse to use it, as
+    # we may clobber some manually generated documentation
+
     def setup_output_dir(op_dir, force)
       flag_file = output_flag_file(op_dir)
       if File.exist?(op_dir)
         unless File.directory?(op_dir)
-          error "'#{op_dir}' exists, and is not a directory" 
+          error "'#{op_dir}' exists, and is not a directory"
         end
         begin
           created = File.read(flag_file)
@@ -129,19 +127,25 @@ module RDoc
       last
     end
 
+    ##
     # Update the flag file in an output directory.
+
     def update_output_dir(op_dir, time)
       File.open(output_flag_file(op_dir), "w") {|f| f.puts time.rfc2822 }
     end
 
+    ##
     # Return the path name of the flag file in an output directory.
+
     def output_flag_file(op_dir)
       File.join(op_dir, "created.rid")
     end
 
-    # The .document file contains a list of file and directory name
-    # patterns, representing candidates for documentation. It may
-    # also contain comments (starting with '#')
+    ##
+    # The .document file contains a list of file and directory name patterns,
+    # representing candidates for documentation. It may also contain comments
+    # (starting with '#')
+
     def parse_dot_doc_file(in_dir, filename, options)
       # read and strip comments
       patterns = File.read(filename).gsub(/#.*/, '')
@@ -155,20 +159,20 @@ module RDoc
       result
     end
 
-
-    # Given a list of files and directories, create a list
-    # of all the Ruby files they contain. 
-    #
-    # If +force_doc+ is true, we always add the given files.
-    # If false, only add files that we guarantee we can parse
-    # It is true when looking at files given on the command line,
-    # false when recursing through subdirectories. 
+    ##
+    # Given a list of files and directories, create a list of all the Ruby
+    # files they contain.
     #
-    # The effect of this is that if you want a file with a non-
-    # standard extension parsed, you must name it explicity.
+    # If +force_doc+ is true we always add the given files, if false, only
+    # add files that we guarantee we can parse.  It is true when looking at
+    # files given on the command line, false when recursing through
+    # subdirectories.
     #
+    # The effect of this is that if you want a file with a non-standard
+    # extension parsed, you must name it explicity.
 
-    def normalized_file_list(options, relative_files, force_doc = false, exclude_pattern=nil)
+    def normalized_file_list(options, relative_files, force_doc = false,
+                             exclude_pattern = nil)
       file_list = []
 
       relative_files.each do |rel_file_name|
@@ -187,27 +191,27 @@ module RDoc
             file_list.concat(list_files_in_directory(rel_file_name, options))
           end
         else
-          raise RDocError.new("I can't deal with a #{type} #{rel_file_name}")
+          raise RDoc::Error, "I can't deal with a #{type} #{rel_file_name}"
         end
       end
+
       file_list
     end
 
-    # Return a list of the files to be processed in
-    # a directory. We know that this directory doesn't have
-    # a .document file, so we're looking for real files. However
-    # we may well contain subdirectories which must
-    # be tested for .document files
+    ##
+    # Return a list of the files to be processed in a directory. We know that
+    # this directory doesn't have a .document file, so we're looking for real
+    # files. However we may well contain subdirectories which must be tested
+    # for .document files.
+
     def list_files_in_directory(dir, options)
       normalized_file_list(options, Dir.glob(File.join(dir, "*")), false, options.exclude)
     end
 
-
-    # Parse each file on the command line, recursively entering
-    # directories
+    ##
+    # Parse each file on the command line, recursively entering directories.
 
     def parse_files(options)
- 
       file_info = []
 
       files = options.files
@@ -217,7 +221,7 @@ module RDoc
 
       file_list.each do |fn|
         $stderr.printf("\n%35s: ", File.basename(fn)) unless options.quiet
-        
+
         content = File.open(fn, "r:ascii-8bit") {|f| f.read}
         if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
           if enc = Encoding.find($1)
@@ -234,32 +238,30 @@ module RDoc
       file_info
     end
 
-
     public
 
-    ###################################################################
-    #
+    ##
     # Format up one or more files according to the given arguments.
-    # For simplicity, _argv_ is an array of strings, equivalent to the
-    # strings that would be passed on the command line. (This isn't a
-    # coincidence, as we _do_ pass in ARGV when running
-    # interactively). For a list of options, see rdoc/rdoc.rb. By
-    # default, output will be stored in a directory called +doc+ below
-    # the current directory, so make sure you're somewhere writable
-    # before invoking.
     #
-    # Throws: RDocError on error
+    # For simplicity, _argv_ is an array of strings, equivalent to the strings
+    # that would be passed on the command line. (This isn't a coincidence, as
+    # we _do_ pass in ARGV when running interactively). For a list of options,
+    # see rdoc/rdoc.rb. By default, output will be stored in a directory
+    # called +doc+ below the current directory, so make sure you're somewhere
+    # writable before invoking.
+    #
+    # Throws: RDoc::Error on error
 
     def document(argv)
-
       TopLevel::reset
 
       @stats = Stats.new
 
-      options = Options.instance
-      options.parse(argv, GENERATORS)
+      options = Options.new GENERATORS
+      options.parse argv
 
       @last_created = nil
+
       unless options.all_one_file
         @last_created = setup_output_dir(options.op_dir, options.force_update)
       end
@@ -298,5 +300,6 @@ module RDoc
       end
     end
   end
+
 end