Import RDoc 3

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

1 files changed, 368 insertions, 91 deletions

diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index 90415f0aa4..810f7fac0a 100644
--- a/lib/rdoc/options.rb
+++ b/lib/rdoc/options.rb
@@ -8,9 +8,41 @@ require 'rdoc/ri/paths'
 class RDoc::Options
 
   ##
-  # Character-set
+  # The deprecated options.
+
+  DEPRECATED = {
+    '--accessor'      => 'support discontinued',
+    '--diagram'       => 'support discontinued',
+    '--help-output'   => 'support discontinued',
+    '--image-format'  => 'was an option for --diagram',
+    '--inline-source' => 'source code is now always inlined',
+    '--merge'         => 'ri now always merges class information',
+    '--one-file'      => 'support discontinued',
+    '--op-name'       => 'support discontinued',
+    '--opname'        => 'support discontinued',
+    '--promiscuous'   => 'files always only document their content',
+    '--ri-system'     => 'Ruby installers use other techniques',
+  }
 
-  attr_reader :charset
+  ##
+  # Template option validator for OptionParser
+
+  Template = nil
+
+  ##
+  # Character-set for HTML output.  #encoding is preferred over #charset
+
+  attr_accessor :charset
+
+  ##
+  # If true, RDoc will not write any files.
+
+  attr_accessor :dry_run
+
+  ##
+  # Encoding of output where.  This is set via --encoding.
+
+  attr_accessor :encoding if Object.const_defined? :Encoding
 
   ##
   # Files matching this pattern will be excluded
@@ -23,9 +55,20 @@ class RDoc::Options
   attr_accessor :files
 
   ##
+  # Create the output even if the output directory does not look
+  # like an rdoc output directory
+
+  attr_accessor :force_output
+
+  ##
   # Scan newer sources than the flag file if true.
 
-  attr_reader :force_update
+  attr_accessor :force_update
+
+  ##
+  # Formatter to mark up text with
+
+  attr_accessor :formatter
 
   ##
   # Description of the output generator (set with the <tt>-fmt</tt> option)
@@ -33,9 +76,21 @@ class RDoc::Options
   attr_accessor :generator
 
   ##
-  # Formatter to mark up text with
+  # Loaded generator options.  Used to prevent --help from loading the same
+  # options multiple times.
 
-  attr_accessor :formatter
+  attr_accessor :generator_options
+
+  ##
+  # Old rdoc behavior: hyperlink all words that match a method name,
+  # even if not preceded by '#' or '::'
+
+  attr_accessor :hyperlink_all
+
+  ##
+  # Include line numbers in the source code
+
+  attr_accessor :line_numbers
 
   ##
   # Name of the file, class or module to display in the initial index page (if
@@ -44,44 +99,54 @@ class RDoc::Options
   attr_accessor :main_page
 
   ##
+  # If true, only report on undocumented files
+
+  attr_accessor :coverage_report
+
+  ##
   # The name of the output directory
 
   attr_accessor :op_dir
 
   ##
-  # Is RDoc in pipe mode?
+  # The OptionParser for this instance
 
-  attr_accessor :pipe
+  attr_accessor :option_parser
 
   ##
-  # Array of directories to search for files to satisfy an :include:
+  # Is RDoc in pipe mode?
 
-  attr_reader :rdoc_include
+  attr_accessor :pipe
 
   ##
-  # Include private and protected methods in the output?
+  # Array of directories to search for files to satisfy an :include:
 
-  attr_accessor :show_all
+  attr_accessor :rdoc_include
 
   ##
   # Include the '#' at the front of hyperlinked instance method names
 
-  attr_reader :show_hash
+  attr_accessor :show_hash
 
   ##
   # The number of columns in a tab
 
-  attr_reader :tab_width
+  attr_accessor :tab_width
 
   ##
   # Template to be used when generating output
 
-  attr_reader :template
+  attr_accessor :template
+
+  ##
+  # Directory the template lives in
+
+  attr_accessor :template_dir
 
   ##
   # Documentation title
 
-  attr_reader :title
+  attr_accessor :title
 
   ##
   # Verbosity, zero means quiet
@@ -91,29 +156,88 @@ class RDoc::Options
   ##
   # URL of web cvs frontend
 
-  attr_reader :webcvs
+  attr_accessor :webcvs
+
+  ##
+  # Minimum visibility of a documented method. One of +:public+,
+  # +:protected+, +:private+. May be overridden on a per-method
+  # basis with the :doc: directive.
+
+  attr_accessor :visibility
 
   def initialize # :nodoc:
     require 'rdoc/rdoc'
-    @op_dir = nil
-    @show_all = false
-    @main_page = nil
+    @dry_run = false
     @exclude = []
-    @generators = RDoc::RDoc::GENERATORS
-    @generator = RDoc::Generator::Darkfish
+    @force_output = false
+    @force_update = true
+    @generator = nil
     @generator_name = nil
+    @generator_options = []
+    @generators = RDoc::RDoc::GENERATORS
+    @hyperlink_all = false
+    @line_numbers = false
+    @main_page = nil
+    @coverage_report = false
+    @op_dir = nil
+    @pipe = false
     @rdoc_include = []
-    @title = nil
-    @template = nil
     @show_hash = false
+    @stylesheet_url = nil
     @tab_width = 8
-    @force_update = true
+    @template = nil
+    @template_dir = nil
+    @title = nil
     @verbosity = 1
-    @pipe = false
-
+    @visibility = :protected
     @webcvs = nil
 
-    @charset = 'utf-8'
+    if Object.const_defined? :Encoding then
+      @encoding = Encoding.default_external
+      @charset = @encoding.to_s
+    else
+      @charset = 'UTF-8'
+    end
+  end
+
+  ##
+  # Check that the files on the command line exist
+
+  def check_files
+    @files.delete_if do |file|
+      if File.exist? file then
+        if File.readable? file then
+          false
+        else
+          warn "file '#{file}' not readable"
+
+          true
+        end
+      else
+        warn "file '#{file}' not found"
+
+        true
+      end
+    end
+  end
+
+  ##
+  # Ensure only one generator is loaded
+
+  def check_generator
+    if @generator then
+      raise OptionParser::InvalidOption,
+        "generator already set to #{@generator_name}"
+    end
+  end
+
+  ##
+  # Set the title, but only if not already set. Used to set the title
+  # from a source file, so that a title set from the command line
+  # will have the priority.
+
+  def default_title=(string)
+    @title ||= string
   end
 
   ##
@@ -122,7 +246,10 @@ class RDoc::Options
   def parse(argv)
     ignore_invalid = true
 
+    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
+
     opts = OptionParser.new do |opt|
+      @option_parser = opt
       opt.program_name = File.basename $0
       opt.version = RDoc::VERSION
       opt.release = nil
@@ -139,6 +266,14 @@ Usage: #{opt.program_name} [options] [names...]
   How RDoc generates output depends on the output formatter being used, and on
   the options you give.
 
+  Options can be specified via the RDOCOPT environment variable, which
+  functions similar to the RUBYOPT environment variable for ruby.
+
+    $ export RDOCOPT="--show-hash"
+
+  will make rdoc show hashes in method links by default.  Command-line options
+  always will override those in RDOCOPT.
+
   - Darkfish creates frameless HTML output by Michael Granger.
   - ri creates ri data files
 
@@ -156,14 +291,44 @@ Usage: #{opt.program_name} [options] [names...]
         opt.banner << "  - #{parser}: #{regexp.join ', '}\n"
       end
 
+      opt.banner << "\n  The following options are deprecated:\n\n"
+
+      name_length = DEPRECATED.keys.sort_by { |k| k.length }.last.length
+
+      DEPRECATED.sort_by { |k,| k }.each do |name, reason|
+        opt.banner << "    %*1$2$s  %3$s\n" % [-name_length, name, reason]
+      end
+
+      opt.accept Template do |template|
+        template_dir = template_dir_for template
+
+        unless template_dir then
+          warn "could not find template #{template}"
+          nil
+        else
+          [template, template_dir]
+        end
+      end
+
       opt.separator nil
-      opt.separator "Parsing Options:"
+      opt.separator "Parsing options:"
       opt.separator nil
 
+      if Object.const_defined? :Encoding then
+        opt.on("--encoding=ENCODING", "-e", Encoding.list.map { |e| e.name },
+               "Specifies the output encoding.  All files",
+               "read will be converted to this encoding.",
+               "Preferred over --charset") do |value|
+                 @encoding = Encoding.find value
+                 @charset = @encoding.to_s # may not be valid value
+               end
+
+        opt.separator nil
+      end
+
       opt.on("--all", "-a",
-             "Include all methods (not just public) in",
-             "the output.") do |value|
-        @show_all = value
+             "Synonym for --visibility=private.") do |value|
+        @visibility = :private
       end
 
       opt.separator nil
@@ -207,20 +372,41 @@ Usage: #{opt.program_name} [options] [names...]
       end
 
       opt.separator nil
-      opt.separator "Generator Options:"
+
+      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
+             "Set the width of tab characters.") do |value|
+        @tab_width = value
+      end
+
       opt.separator nil
 
-      opt.on("--charset=CHARSET", "-c",
-             "Specifies the output HTML character-set.") do |value|
-        @charset = value
+      opt.on("--visibility=VISIBILITY", "-V", RDoc::VISIBILITIES,
+             "Minimum visibility to document a method.",
+             "One of 'public', 'protected' (the default)",
+             "or 'private'. Can be abbreviated.") do |value|
+        @visibility = value
+      end
+
+      opt.separator nil
+      opt.separator "Common generator options:"
+      opt.separator nil
+
+      opt.on("--force-output", "-O",
+             "Forces rdoc to write the output files,",
+             "even if the output directory exists",
+             "and does not seem to have been created",
+             "by rdoc.") do |value|
+        @force_output = value
       end
 
       opt.separator nil
 
       generator_text = @generators.keys.map { |name| "  #{name}" }.sort
 
-      opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys,
+      opt.on("-f", "--fmt=FORMAT", "--format=FORMAT", @generators.keys,
              "Set the output formatter.  One of:", *generator_text) do |value|
+        check_generator
+
         @generator_name = value.downcase
         setup_generator
       end
@@ -236,9 +422,11 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--main=NAME", "-m",
-             "NAME will be the initial page displayed.") do |value|
-        @main_page = value
+      opt.on("--[no-]coverage-report", "--[no-]dcov", "-C",
+             "Prints a report on undocumented items.",
+             "Does not generate files.") do |value|
+        @coverage_report = value
+        @force_update = true if value
       end
 
       opt.separator nil
@@ -250,6 +438,51 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      opt.on("-d",
+             "Deprecated --diagram option.",
+             "Prevents firing debug mode",
+             "with legacy invocation.") do |value|
+      end
+
+      opt.separator nil
+      opt.separator 'HTML generator options:'
+      opt.separator nil
+
+      opt.on("--charset=CHARSET", "-c",
+             "Specifies the output HTML character-set.",
+             "Use --encoding instead of --charset if",
+             "available.") do |value|
+        @charset = value
+      end
+
+      opt.separator nil
+
+      opt.on("--hyperlink-all", "-A",
+             "Generate hyperlinks for all words that",
+             "correspond to known methods, even if they",
+             "do not start with '#' or '::' (legacy",
+             "behavior).") do |value|
+        @hyperlink_all = value
+      end
+
+      opt.separator nil
+
+      opt.on("--main=NAME", "-m",
+             "NAME will be the initial page displayed.") do |value|
+        @main_page = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]line-numbers", "-N",
+             "Include line numbers in the source code.",
+             "By default, only the number of the first",
+             "line is displayed, in a leading comment.") do |value|
+        @line_numbers = value
+      end
+
+      opt.separator nil
+
       opt.on("--show-hash", "-H",
              "A name of the form #name in a comment is a",
              "possible hyperlink to an instance method",
@@ -260,17 +493,12 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
-             "Set the width of tab characters.") do |value|
-        @tab_width = value
-      end
-
-      opt.separator nil
-
-      opt.on("--template=NAME", "-T",
+      opt.on("--template=NAME", "-T", Template,
              "Set the template used when generating",
-             "output.") do |value|
-        @template = value
+             "output. The default depends on the",
+             "formatter used.") do |(template, template_dir)|
+        @template     = template
+        @template_dir = template_dir
       end
 
       opt.separator nil
@@ -292,11 +520,7 @@ Usage: #{opt.program_name} [options] [names...]
       end
 
       opt.separator nil
-
-      opt.on("-d", "--diagram", "Prevents -d from tripping --debug")
-
-      opt.separator nil
-      opt.separator "ri Generator Options:"
+      opt.separator "ri generator options:"
       opt.separator nil
 
       opt.on("--ri", "-r",
@@ -305,6 +529,8 @@ Usage: #{opt.program_name} [options] [names...]
              "your home directory unless overridden by a",
              "subsequent --op parameter, so no special",
              "privileges are needed.") do |value|
+        check_generator
+
         @generator_name = "ri"
         @op_dir ||= RDoc::RI::Paths::HOMEDIR
         setup_generator
@@ -317,22 +543,30 @@ Usage: #{opt.program_name} [options] [names...]
              "are stored in a site-wide directory,",
              "making them accessible to others, so",
              "special privileges are needed.") do |value|
+        check_generator
+
         @generator_name = "ri"
         @op_dir = RDoc::RI::Paths::SITEDIR
         setup_generator
       end
 
       opt.separator nil
-      opt.separator "Generic Options:"
+      opt.separator "Generic options:"
       opt.separator nil
 
+      opt.on("--[no-]dry-run",
+             "Don't write any files") do |value|
+        @dry_run = value
+      end
+
       opt.on("-D", "--[no-]debug",
              "Displays lots on internal stuff.") do |value|
         $DEBUG_RDOC = value
       end
 
       opt.on("--[no-]ignore-invalid",
-             "Ignore invalid options and continue.") do |value|
+             "Ignore invalid options and continue",
+             "(default true).") do |value|
         ignore_invalid = value
       end
 
@@ -342,38 +576,70 @@ Usage: #{opt.program_name} [options] [names...]
       end
 
       opt.on("--verbose", "-v",
-             "Display extra progress as we parse.") do |value|
+             "Display extra progress as RDoc parses") do |value|
         @verbosity = 2
       end
 
+      opt.on("--help",
+             "Display this help") do
+        RDoc::RDoc::GENERATORS.each_key do |generator|
+          setup_generator generator
+        end
+
+        puts opt.help
+        exit
+      end
+
       opt.separator nil
     end
 
-    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
-    ignored = []
+    setup_generator 'darkfish' if
+      argv.grep(/\A(-f|--fmt|--format|-r|-R|--ri|--ri-site)\b/).empty?
+
+    deprecated = []
+    invalid = []
 
     begin
       opts.parse! argv
     rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
-      if ignore_invalid then
-        ignored << e.args.join(' ')
-        retry
+      if DEPRECATED[e.args.first] then
+        deprecated << e.args.first
+      elsif %w[--format --ri -r --ri-site -R].include? e.args.first then
+        raise
       else
-        $stderr.puts opts
-        $stderr.puts
-        $stderr.puts e
-        exit 1
+        invalid << e.args.join(' ')
       end
+
+      retry
+    end
+
+    unless @generator then
+      @generator = RDoc::Generator::Darkfish
+      @generator_name = 'darkfish'
     end
 
     if @pipe and not argv.empty? then
       @pipe = false
-      ignored << '-p (with files)'
+      invalid << '-p (with files)'
     end
 
-    unless ignored.empty? or quiet then
-      $stderr.puts "invalid options: #{ignored.join ', '}"
-      $stderr.puts '(invalid options are ignored)'
+    unless quiet then
+      deprecated.each do |opt|
+        $stderr.puts 'option ' << opt << ' is deprecated: ' << DEPRECATED[opt]
+      end
+
+      unless invalid.empty? then
+        invalid = "invalid options: #{invalid.join ', '}"
+
+        if ignore_invalid then
+          $stderr.puts invalid
+          $stderr.puts '(invalid options are ignored)'
+        else
+          $stderr.puts opts
+          $stderr.puts invalid
+          exit 1
+        end
+      end
     end
 
     @op_dir ||= 'doc'
@@ -392,15 +658,10 @@ Usage: #{opt.program_name} [options] [names...]
     # If no template was specified, use the default template for the output
     # formatter
 
-    @template ||= @generator_name
-  end
-
-  ##
-  # Set the title, but only if not already set. This means that a title set
-  # from the command line trumps one set in a source file
-
-  def title=(string)
-    @title ||= string
+    unless @template then
+      @template     = @generator_name
+      @template_dir = template_dir_for @template
+    end
   end
 
   ##
@@ -410,30 +671,46 @@ Usage: #{opt.program_name} [options] [names...]
     @verbosity.zero?
   end
 
-  def quiet=(bool)
+  ##
+  # Set quietness to +bool+
+
+  def quiet= bool
     @verbosity = bool ? 0 : 1
   end
 
-  private
-
   ##
-  # Set up an output generator for the format in @generator_name
+  # Set up an output generator for the named +generator_name+.
+  #
+  # If the found generator responds to :setup_options it will be called with
+  # the options instance.  This allows generators to add custom options or set
+  # default options.
 
-  def setup_generator
-    @generator = @generators[@generator_name]
+  def setup_generator generator_name = @generator_name
+    @generator = @generators[generator_name]
 
     unless @generator then
-      raise OptionParser::InvalidArgument, "Invalid output formatter"
+      raise OptionParser::InvalidArgument,
+            "Invalid output formatter #{generator_name}"
     end
+
+    return if @generator_options.include? @generator
+
+    @generator_name = generator_name
+    @generator_options << @generator
+
+    @generator.setup_options self if @generator.respond_to? :setup_options
   end
 
   ##
-  # Check that the files on the command line exist
+  # Finds the template dir for +template+
 
-  def check_files
-    @files.each do |f|
-      stat = File.stat f rescue next
-      raise RDoc::Error, "file '#{f}' not readable" unless stat.readable?
+  def template_dir_for template
+    template_path = File.join 'rdoc', 'generator', 'template', template
+
+    $LOAD_PATH.map do |path|
+      File.join File.expand_path(path), template_path
+    end.find do |dir|
+      File.directory? dir
     end
   end