Import RDoc 3

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

1 files changed, 68 insertions, 36 deletions

diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb
index 8771b408d9..a885d8dded 100644
--- a/lib/rdoc/rdoc.rb
+++ b/lib/rdoc/rdoc.rb
@@ -1,5 +1,6 @@
 require 'rdoc'
 
+require 'rdoc/encoding'
 require 'rdoc/parser'
 
 # Simple must come first
@@ -23,7 +24,28 @@ require 'time'
 #   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 for details.
+# give rdoc on the command line.  See <tt>rdoc --help<tt> for details.
+#
+# = Plugins
+#
+# When you <tt>require 'rdoc/rdoc'</tt> RDoc looks for 'rdoc/discover' files
+# in your installed gems.  This can be used to load alternate generators or
+# add additional preprocessor directives.
+#
+# You will want to wrap your plugin loading in an RDoc version check.
+# Something like:
+#
+#   begin
+#     gem 'rdoc', '~> 3'
+#     require 'path/to/my/awesome/rdoc/plugin'
+#   rescue Gem::LoadError
+#   end
+#
+# The most obvious plugin type is a new output generator.  See RDoc::Generator
+# for details.
+#
+# You can also hook into RDoc::Markup to add new directives (:nodoc: is a
+# directive).  See RDoc::Markup::PreProcess::register for details.
 
 class RDoc::RDoc
 
@@ -79,6 +101,10 @@ class RDoc::RDoc
     @current = rdoc
   end
 
+  ##
+  # Creates a new RDoc::RDoc instance.  Call #document to parse files and
+  # generate documentation.
+
   def initialize
     @current       = nil
     @exclude       = nil
@@ -142,7 +168,9 @@ class RDoc::RDoc
 
     last = {}
 
-    if File.exist? dir then
+    if @options.dry_run then
+      # do nothing
+    elsif File.exist? dir then
       error "#{dir} exists and is not a directory" unless File.directory? dir
 
       begin
@@ -167,7 +195,7 @@ you'll need to specify a different output directory name (using the --op <dir>
 option)
 
         ERROR
-      end
+      end unless @options.force_output
     else
       FileUtils.mkdir_p dir
     end
@@ -179,6 +207,8 @@ option)
   # Update the flag file in an output directory.
 
   def update_output_dir(op_dir, time, last = {})
+    return if @options.dry_run
+
     open output_flag_file(op_dir), "w" do |f|
       f.puts time.rfc2822
       last.each do |n, t|
@@ -277,7 +307,9 @@ option)
 
   def parse_file filename
     @stats.add_file filename
-    content = read_file_contents filename
+    encoding = @options.encoding if defined?(Encoding)
+
+    content = RDoc::Encoding.read_file filename, encoding
 
     return unless content
 
@@ -288,11 +320,22 @@ option)
     return unless parser
 
     parser.scan
+
+    # restart documentation for the classes & modules found
+    top_level.classes_or_modules.each do |cm|
+      cm.done_documenting = false
+    end
+
+    top_level
+
   rescue => e
     $stderr.puts <<-EOF
 Before reporting this, could you check that the file you're documenting
-compiles cleanly--RDoc is not a full Ruby parser, and gets confused easily if
-fed invalid programs.
+has proper syntax:
+
+  #{Gem.ruby} -c #{filename}
+
+RDoc is not a full Ruby parser and will fail when fed invalid ruby programs.
 
 The internal error was:
 
@@ -300,7 +343,7 @@ The internal error was:
 
     EOF
 
-    $stderr.puts e.backtrace.join("\n\t") if $RDOC_DEBUG
+    $stderr.puts e.backtrace.join("\n\t") if $DEBUG_RDOC
 
     raise e
     nil
@@ -344,11 +387,9 @@ The internal error was:
   # 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
+  # see <tt>rdoc --help</tt>. 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)
     RDoc::TopLevel.reset
@@ -364,29 +405,36 @@ The internal error was:
 
     @exclude = @options.exclude
 
-    @last_modified = setup_output_dir @options.op_dir, @options.force_update
+    unless @options.coverage_report then
+      @last_modified = setup_output_dir @options.op_dir, @options.force_update
+    end
 
     start_time = Time.now
 
     file_info = parse_files @options.files
 
-    @options.title = "RDoc Documentation"
+    @options.default_title = "RDoc Documentation"
+
+    RDoc::TopLevel.complete @options.visibility
 
-    if file_info.empty?
+    if @options.coverage_report then
+      puts
+      puts @stats.report
+    elsif file_info.empty?
       $stderr.puts "\nNo newer files." unless @options.quiet
     else
       gen_klass = @options.generator
 
-      unless @options.quiet then
-        $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')}..."
-      end
-
-      @generator = gen_klass.for @options
+      @generator = gen_klass.new @options
 
       Dir.chdir @options.op_dir do
         begin
           self.class.current = self
 
+          unless @options.quiet then
+            $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
+          end
+
           @generator.generate file_info
           update_output_dir ".", start_time, @last_modified
         ensure
@@ -397,26 +445,10 @@ The internal error was:
 
     unless @options.quiet or not @stats then
       puts
-      @stats.print
-    end
-  end
-
-  def read_file_contents(filename)
-    content = open filename, "rb" do |f| f.read end
-
-    utf8 = content.sub!(/\A\xef\xbb\xbf/, '')
-    if defined? Encoding then
-      if /coding[=:]\s*([^\s;]+)/i =~ content[%r"\A(?:#!.*\n)?.*\n"]
-        enc = ::Encoding.find($1)
-      end
-      if enc ||= (Encoding::UTF_8 if utf8)
-        content.force_encoding(enc)
-      end
+      puts @stats.summary
     end
 
-    content
-  rescue Errno::EISDIR, Errno::ENOENT
-    nil
+    exit @stats.fully_documented? if @options.coverage_report
   end
 
   ##