Import RDoc 3.1

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

15 files changed, 159 insertions, 40 deletions

diff --git a/lib/rdoc.rb b/lib/rdoc.rb
index a453ee1039..ef02b43027 100644
--- a/lib/rdoc.rb
+++ b/lib/rdoc.rb
@@ -95,7 +95,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '3.0'
+  VERSION = '3.1'
 
   ##
   # Method visibilities
diff --git a/lib/rdoc/class_module.rb b/lib/rdoc/class_module.rb
index 1e75699ffa..64ccfdabd6 100644
--- a/lib/rdoc/class_module.rb
+++ b/lib/rdoc/class_module.rb
@@ -118,7 +118,8 @@ class RDoc::ClassModule < RDoc::Context
   def comment= comment
     return if comment.empty?
 
-    comment = "#{@comment}\n---\n#{normalize_comment comment}" unless
+    comment = normalize_comment comment
+    comment = "#{@comment}\n---\n#{comment}" unless
       @comment.empty?
 
     super
diff --git a/lib/rdoc/encoding.rb b/lib/rdoc/encoding.rb
index 4f0779881c..73ae505daf 100644
--- a/lib/rdoc/encoding.rb
+++ b/lib/rdoc/encoding.rb
@@ -60,8 +60,6 @@ module RDoc::Encoding
   # Sets the encoding of +string+ based on the magic comment
 
   def self.set_encoding string
-    return unless Object.const_defined? :Encoding
-
     first_line = string[/\A(?:#!.*\n)?.*\n/]
 
     name = case first_line
@@ -70,6 +68,10 @@ module RDoc::Encoding
            else                                           return
            end
 
+    string.sub! first_line, ''
+
+    return unless Object.const_defined? :Encoding
+
     enc = Encoding.find name
     string.force_encoding enc if enc
   end
diff --git a/lib/rdoc/generator/darkfish.rb b/lib/rdoc/generator/darkfish.rb
index e5a6e57424..57873468e4 100644
--- a/lib/rdoc/generator/darkfish.rb
+++ b/lib/rdoc/generator/darkfish.rb
@@ -64,6 +64,11 @@ class RDoc::Generator::Darkfish
   VERSION = '2'
 
   ##
+  # Description of this generator
+
+  DESCRIPTION = 'HTML generator, written by Michael Granger'
+
+  ##
   # Initialize a few instance variables before we start
 
   def initialize options
diff --git a/lib/rdoc/generator/ri.rb b/lib/rdoc/generator/ri.rb
index fb52997e89..e02805e40f 100644
--- a/lib/rdoc/generator/ri.rb
+++ b/lib/rdoc/generator/ri.rb
@@ -9,6 +9,11 @@ class RDoc::Generator::RI
   RDoc::RDoc.add_generator self
 
   ##
+  # Description of this generator
+
+  DESCRIPTION = 'creates ri data files'
+
+  ##
   # Set up a new ri generator
 
   def initialize options #:not-new:
diff --git a/lib/rdoc/generator/template/darkfish/classpage.rhtml b/lib/rdoc/generator/template/darkfish/classpage.rhtml
index 72b86ec6a7..7d0cad0eed 100644
--- a/lib/rdoc/generator/template/darkfish/classpage.rhtml
+++ b/lib/rdoc/generator/template/darkfish/classpage.rhtml
@@ -134,7 +134,7 @@
       <% end %>
 
       <div id="classindex-section" class="section project-section">
-        <h3 class="section-header">Class Index
+        <h3 class="section-header">Class/Module Index
           <span class="search-toggle"><img src="<%= rel_prefix %>/images/find.png"
             height="16" width="16" alt="[+]"
             title="show/hide quicksearch" /></span></h3>
@@ -225,16 +225,22 @@
       <div id="<%= method.html_name %>-method" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>">
         <a name="<%= h method.aref %>"></a>
 
-        <div class="method-heading">
         <% if method.call_seq %>
-          <span class="method-callseq"><%= method.call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w.+\./m, '') %></span>
+        <% method.call_seq.strip.split("\n").each_with_index do |call_seq, i| %>
+        <div class="method-heading">
+          <span class="method-callseq"><%= call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w.+\./m, '') %></span>
+          <% if i == 0 %>
           <span class="method-click-advice">click to toggle source</span>
+          <% end %>
+        </div>
+        <% end %>
         <% else %>
+        <div class="method-heading">
           <span class="method-name"><%= h method.name %></span><span
             class="method-args"><%= method.params %></span>
           <span class="method-click-advice">click to toggle source</span>
-        <% end %>
         </div>
+        <% end %>
 
         <div class="method-description">
           <% if method.comment %>
diff --git a/lib/rdoc/markup/to_html.rb b/lib/rdoc/markup/to_html.rb
index de723921e9..66f5c1986d 100644
--- a/lib/rdoc/markup/to_html.rb
+++ b/lib/rdoc/markup/to_html.rb
@@ -27,6 +27,11 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   attr_reader :list # :nodoc:
 
   ##
+  # Path to this document for relative links
+
+  attr_accessor :from_path
+
+  ##
   # Converts a target url to one that is relative to a given path
 
   def self.gen_relative_url(path, target)
@@ -59,6 +64,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @th = nil
     @in_list_entry = nil
     @list = nil
+    @from_path = ''
 
     # external hyperlinks
     @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
@@ -79,8 +85,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Generate a hyperlink for url, labeled with text. Handle the
-  # special cases for img: and link: described under handle_special_HYPERLINK
+  # Generate a hyperlink for +url+, labeled with +text+.  Handles the special
+  # cases for img: and link: described under handle_special_HYPERLINK
 
   def gen_url(url, text)
     if url =~ /([A-Za-z]+):(.*)/ then
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index 810f7fac0a..3d76569a7e 100644
--- a/lib/rdoc/options.rb
+++ b/lib/rdoc/options.rb
@@ -241,6 +241,32 @@ class RDoc::Options
   end
 
   ##
+  # Returns a properly-space list of generators and their descriptions.
+
+  def generator_descriptions
+    lengths = []
+
+    generators = RDoc::RDoc::GENERATORS.map do |name, generator|
+      lengths << name.length
+
+      description = generator::DESCRIPTION if
+        generator.const_defined? :DESCRIPTION
+
+      [name, description]
+    end
+
+    longest = lengths.max
+
+    generators.sort.map do |name, description|
+      if description then
+        "  %-*s - %s" % [longest, name, description]
+      else
+        "  #{name}"
+      end
+    end.join "\n"
+  end
+
+  ##
   # Parse command line options.
 
   def parse(argv)
@@ -274,8 +300,9 @@ Usage: #{opt.program_name} [options] [names...]
   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
+  Available formatters:
+
+#{generator_descriptions}
 
   RDoc understands the following file formats:
 
diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb
index 60e9fefd61..db37985b6d 100644
--- a/lib/rdoc/parser/c.rb
+++ b/lib/rdoc/parser/c.rb
@@ -371,7 +371,7 @@ class RDoc::Parser::C < RDoc::Parser
 
   def find_body(class_name, meth_name, meth_obj, body, quiet = false)
     case body
-    when %r%((?>/\*.*?\*/\s*))
+    when %r%((?>/\*.*?\*/\s*)?)
             ((?:(?:static|SWIGINTERN)\s+)?
              (?:intern\s+)?VALUE\s+#{meth_name}
              \s*(\([^)]*\))([^;]|$))%xm then
@@ -547,7 +547,7 @@ class RDoc::Parser::C < RDoc::Parser
     # with ARGF at the same indent, but that are after the first description
     # paragraph.
 
-    if comment =~ /call-seq:(.*?[^\s\*].*?)^\s*\*?\s*$/m then
+    if comment =~ /call-seq:(.*?(?:\S|\*\/?).*?)^\s*(?:\*\/?)?\s*$/m then
       all_start, all_stop = $~.offset(0)
       seq_start, seq_stop = $~.offset(1)
 
diff --git a/lib/rdoc/parser/ruby.rb b/lib/rdoc/parser/ruby.rb
index e6f07d66da..bec88bc52d 100644
--- a/lib/rdoc/parser/ruby.rb
+++ b/lib/rdoc/parser/ruby.rb
@@ -224,9 +224,11 @@ class RDoc::Parser::Ruby < RDoc::Parser
   ##
   # Look for a 'call-seq' in the comment, and override the normal parameter
   # stuff
+  #--
+  # TODO handle undent
 
   def extract_call_seq(comment, meth)
-    if comment.sub!(/:?call-seq:(.*?)^\s*\#?\s*$/m, '') then
+    if comment.sub!(/:?call-seq:(.*?)(^\s*#?\s*$|\z)/m, '') then
       seq = $1
       seq.gsub!(/^\s*\#\s*/, '')
       meth.call_seq = seq
@@ -779,6 +781,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
       @stats.add_attribute att
     end
+
+    true
   end
 
   ##
@@ -1230,10 +1234,10 @@ class RDoc::Parser::Ruby < RDoc::Parser
         if TkCOMMENT === tk then
           if non_comment_seen then
             # Look for RDoc in a comment about to be thrown away
-            parse_comment container, tk, comment unless comment.empty?
+            non_comment_seen = parse_comment container, tk, comment unless
+              comment.empty?
 
             comment = ''
-            non_comment_seen = false
           end
 
           while TkCOMMENT === tk do
@@ -1360,6 +1364,11 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
           return
         end
+      else
+        non_comment_seen = parse_comment container, tk, comment unless
+          comment.empty?
+
+        comment = ''
       end
 
       comment = '' unless keep_comment
diff --git a/lib/rdoc/ri/driver.rb b/lib/rdoc/ri/driver.rb
index 9d61b1f243..112d65399c 100644
--- a/lib/rdoc/ri/driver.rb
+++ b/lib/rdoc/ri/driver.rb
@@ -610,7 +610,7 @@ Options may also be set in the 'RI' environment variable.
       end
 
       if class_methods or instance_methods or not klass.constants.empty? then
-        out << RDoc::Markup::Rule.new
+        out << RDoc::Markup::Rule.new(1)
       end
 
       unless klass.constants.empty? then
diff --git a/lib/rdoc/ri/paths.rb b/lib/rdoc/ri/paths.rb
index f44b0e1e95..a3c65bf928 100644
--- a/lib/rdoc/ri/paths.rb
+++ b/lib/rdoc/ri/paths.rb
@@ -19,7 +19,17 @@ module RDoc::RI::Paths
   SYSDIR  = File.join base, "system"
   SITEDIR = File.join base, "site"
 
-  HOMEDIR = File.expand_path('~/.rdoc') rescue nil
+  homedir = begin
+              File.expand_path('~')
+            rescue ArgumentError
+            end
+
+  homedir ||= ENV['HOME'] ||
+              ENV['USERPROFILE'] || ENV['HOMEPATH'] # for 1.8 compatibility
+
+  HOMEDIR = if homedir then
+              File.join homedir, ".rdoc"
+            end
   #:startdoc:
 
   @gemdirs = nil
diff --git a/lib/rdoc/ruby_lex.rb b/lib/rdoc/ruby_lex.rb
index cbe3ec9061..7e84a4ad8e 100644
--- a/lib/rdoc/ruby_lex.rb
+++ b/lib/rdoc/ruby_lex.rb
@@ -541,12 +541,12 @@ class RDoc::RubyLex
       catch(:RET) do
         if @lex_state == EXPR_ARG
           if @space_seen and peek(0) =~ /[0-9]/
-            throw :RET, identify_number
+            throw :RET, identify_number(op)
           else
             @lex_state = EXPR_BEG
           end
         elsif @lex_state != EXPR_END and peek(0) =~ /[0-9]/
-          throw :RET, identify_number
+          throw :RET, identify_number(op)
         else
           @lex_state = EXPR_BEG
         end
@@ -1010,10 +1010,10 @@ class RDoc::RubyLex
     identify_string(lt, @quoted)
   end
 
-  def identify_number
+  def identify_number(op = "")
     @lex_state = EXPR_END
 
-    num = ''
+    num = op
 
     if peek(0) == "0" && peek(1) !~ /[.eE]/
       num << getc
diff --git a/lib/rdoc/stats.rb b/lib/rdoc/stats.rb
index e0af445539..70e361feaa 100644
--- a/lib/rdoc/stats.rb
+++ b/lib/rdoc/stats.rb
@@ -24,6 +24,7 @@ class RDoc::Stats
     @files_so_far = 0
     @num_files = num_files
     @fully_documented = nil
+    @percent_doc = nil
 
     @start = Time.now
 
@@ -215,7 +216,9 @@ class RDoc::Stats
         report << nil
 
         cm.each_constant do |constant|
-          next if constant.documented?
+          # TODO constant aliases are listed in the summary but not reported
+          # figure out what to do here
+          next if constant.documented? || constant.is_alias_for
           report << "  # in file #{constant.file.full_name}"
           report << "  #{constant.name} = nil"
         end
@@ -255,22 +258,36 @@ class RDoc::Stats
   def summary
     calculate
 
+    num_width = [@num_files, @num_items].max.to_s.length
+    nodoc_width = [
+      @undoc_attributes,
+      @undoc_classes,
+      @undoc_constants,
+      @undoc_items,
+      @undoc_methods,
+      @undoc_modules,
+    ].max.to_s.length
+
     report = []
-    report << 'Files:      %5d' % @num_files
+    report << 'Files:      %*d' % [num_width, @num_files]
+
     report << nil
-    report << 'Classes:    %5d (%5d undocumented)' % [@num_classes,
-                                                      @undoc_classes]
-    report << 'Modules:    %5d (%5d undocumented)' % [@num_modules,
-                                                      @undoc_modules]
-    report << 'Constants:  %5d (%5d undocumented)' % [@num_constants,
-                                                     @undoc_constants]
-    report << 'Attributes: %5d (%5d undocumented)' % [@num_attributes,
-                                                      @undoc_attributes]
-    report << 'Methods:    %5d (%5d undocumented)' % [@num_methods,
-                                                      @undoc_methods]
+
+    report << 'Classes:    %*d (%*d undocumented)' % [
+      num_width, @num_classes, nodoc_width, @undoc_classes]
+    report << 'Modules:    %*d (%*d undocumented)' % [
+      num_width, @num_modules, nodoc_width, @undoc_modules]
+    report << 'Constants:  %*d (%*d undocumented)' % [
+      num_width, @num_constants, nodoc_width, @undoc_constants]
+    report << 'Attributes: %*d (%*d undocumented)' % [
+      num_width, @num_attributes, nodoc_width, @undoc_attributes]
+    report << 'Methods:    %*d (%*d undocumented)' % [
+      num_width, @num_methods, nodoc_width, @undoc_methods]
+
     report << nil
-    report << 'Total:      %5d (%5d undocumented)' % [@num_items,
-                                                      @undoc_items]
+
+    report << 'Total:      %*d (%*d undocumented)' % [
+      num_width, @num_items, nodoc_width, @undoc_items]
 
     report << '%6.2f%% documented' % @percent_doc if @percent_doc
     report << nil
diff --git a/lib/rdoc/task.rb b/lib/rdoc/task.rb
index 005c516eed..4a702e3fa8 100644
--- a/lib/rdoc/task.rb
+++ b/lib/rdoc/task.rb
@@ -53,6 +53,9 @@ require 'rake/tasklib'
 #
 # Simple Example:
 #
+#   gem 'rdoc'
+#   require 'rdoc/task'
+#
 #   RDoc::Task.new do |rd|
 #     rd.main = "README.rdoc"
 #     rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
@@ -67,6 +70,9 @@ require 'rake/tasklib'
 # generating two sets of documentation.  For instance, if you want to have a
 # development set of documentation including private methods:
 #
+#   gem 'rdoc'
+#   require 'rdoc/task'
+#
 #   RDoc::Task.new :rdoc_dev do |rd|
 #     rd.main = "README.doc"
 #     rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
@@ -82,6 +88,9 @@ require 'rake/tasklib'
 #
 # For example:
 #
+#   gem 'rdoc'
+#   require 'rdoc/task'
+#
 #   RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
 #                  :rerdoc => "rdoc:force")
 #
@@ -117,6 +126,11 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :template
 
   ##
+  # Name of format generator (--fmt) used by rdoc. (defaults to rdoc's default)
+
+  attr_accessor :generator
+
+  ##
   # List of files to be included in the rdoc generation. (default is [])
 
   attr_accessor :rdoc_files
@@ -151,12 +165,28 @@ class RDoc::Task < Rake::TaskLib
     @main = nil
     @title = nil
     @template = nil
+    @generator = nil
     @options = []
     yield self if block_given?
     define
   end
 
   ##
+  # All source is inline now.  This method is deprecated
+
+  def inline_source() # :nodoc:
+    warn "RDoc::Task#inline_source is deprecated"
+    true
+  end
+
+  ##
+  # All source is inline now.  This method is deprecated
+
+  def inline_source=(value) # :nodoc:
+    warn "RDoc::Task#inline_source is deprecated"
+  end
+
+  ##
   # Create the tasks defined by this task lib.
 
   def define
@@ -201,9 +231,10 @@ class RDoc::Task < Rake::TaskLib
   def option_list
     result = @options.dup
     result << "-o"      << @rdoc_dir
-    result << "--main"  << main     if main
-    result << "--title" << title    if title
-    result << "-T"      << template if template
+    result << "--main"  << main      if main
+    result << "--title" << title     if title
+    result << "-T"      << template  if template
+    result << '-f'      << generator if generator
     result
   end