rdoc 2.2.0 → 2.2.1

data/History.txt

@@ -1,3 +1,35 @@
+=== 2.2.1 / 2008-09-24
+This version provides some minor fixes and enhancements to 2.2.0 intended
+to polish RDoc for Ruby 1.9.1.
+
+* 3 Minor Enhancements
+  * Support for parsing RDoc from SWIG.  Ruby patch #10742 by Gonzalo
+    Garramuno, #13993 by Steven Jenkins.
+  * Simple support for Perl POD documentation.  Patch by Hugh Sasse.
+  * Changed the default character set of RDoc's output from iso-8859-1 to
+    utf-8.
+
+* 9 Bug Fixes
+  * Explicitly set the html template's text color, so that the generated
+    documentation will display correctly on browsers with custom text and
+    background color settings (patch by Luther Thompson).
+  * Ensure that RDoc correctly will associate an alias and a method, even
+    if it encounters the alias first because the alias lives in a different
+    file.
+  * Fix the parsing of multiline constants (patch by Chris Alfeld and
+    Joel VanderWerf)
+  * Make --exclude usuable.  Ruby patch #11671 by Trans.
+  * Detect inline C functions.  Ruby Bug #11993 by Florian Frank.
+  * Fix an issue in which RDoc might not document a class'
+    superclass correctly if the class was defined in multiple files and
+    depending on the order in which RDoc processed the files.  This should
+    ensure that the child class -> parent class relationship is correct in
+    ri documentation, allowing ri to lookup inherited methods (i.e., File.read).
+  * Stop ri from crashing when it looks for a completely bogus method (i.e.,
+    File#reada).  Now, ri exits with a helpful error message.
+  * Fixed missing display of constant values in ri.
+  * Fixed display of constants in ri's html output.
+
 === 2.2.0 / 2008-09-19
 This version includes some significant enhancements to ri.  See RI.txt for
 documentation about ri.

data/Manifest.txt

@@ -47,6 +47,7 @@ lib/rdoc/options.rb
 lib/rdoc/parser.rb
 lib/rdoc/parser/c.rb
 lib/rdoc/parser/f95.rb
+lib/rdoc/parser/perl.rb
 lib/rdoc/parser/ruby.rb
 lib/rdoc/parser/simple.rb
 lib/rdoc/rdoc.rb
@@ -73,6 +74,7 @@ test/test_rdoc_markup_to_html.rb
 test/test_rdoc_markup_to_html_crossref.rb
 test/test_rdoc_parser.rb
 test/test_rdoc_parser_c.rb
+test/test_rdoc_parser_perl.rb
 test/test_rdoc_parser_ruby.rb
 test/test_rdoc_ri_attribute_formatter.rb
 test/test_rdoc_ri_default_display.rb

data/README.txt

@@ -46,6 +46,10 @@ The markup engine has lots of little bugs.  In particular:
 * Some output formats (ri, for example) do not correctly handle all of the
   markup.
 The markup engine needs a rewrite, which can be tracked here[http://rubyforge.org/tracker/index.php?func=detail&aid=21540&group_id=627&atid=2475].
+---
+RDoc has some subtle bugs processing classes that are split across multiple
+files (bugs that may or may not manifest depending on the order in which
+the files are encountered).  This issue can be tracked here[http://rubyforge.org/tracker/index.php?func=detail&aid=22135&group_id=627&atid=2475].
 -------
 If you find a bug, please report it at the RDoc project's
 tracker[http://rubyforge.org/tracker/?group_id=627] on RubyForge:

data/lib/rdoc.rb

@@ -372,7 +372,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = "2.2.0"
+  VERSION = "2.2.1"
 
   ##
   # Name of the dotfile that contains the description of files to be processed

data/lib/rdoc/code_objects.rb

@@ -302,6 +302,7 @@ module RDoc
       if mod then
         klass.classes_hash.update(mod.classes_hash)
         klass.modules_hash.update(mod.modules_hash)
+        klass.method_list.concat(mod.method_list)
       end
 
       return klass
@@ -314,25 +315,41 @@ module RDoc
     def add_method(a_method)
       a_method.visibility = @visibility
       add_to(@method_list, a_method)
+
+      unmatched_alias_list = @unmatched_alias_lists[a_method.name]
+      if unmatched_alias_list then
+        unmatched_alias_list.each do |unmatched_alias|
+          add_alias_impl unmatched_alias, a_method
+          @aliases.delete unmatched_alias
+        end
+
+        @unmatched_alias_lists.delete a_method.name
+      end
     end
 
     def add_attribute(an_attribute)
       add_to(@attributes, an_attribute)
     end
 
+    def add_alias_impl(an_alias, meth)
+      new_meth = AnyMethod.new(an_alias.text, an_alias.new_name)
+      new_meth.is_alias_for = meth
+      new_meth.singleton    = meth.singleton
+      new_meth.params       = meth.params
+      new_meth.comment = "Alias for \##{meth.name}"
+      meth.add_alias(new_meth)
+      add_method(new_meth)
+    end
+    
     def add_alias(an_alias)
       meth = find_instance_method_named(an_alias.old_name)
 
       if meth then
-        new_meth = AnyMethod.new(an_alias.text, an_alias.new_name)
-        new_meth.is_alias_for = meth
-        new_meth.singleton    = meth.singleton
-        new_meth.params       = meth.params
-        new_meth.comment = "Alias for \##{meth.name}"
-        meth.add_alias(new_meth)
-        add_method(new_meth)
+        add_alias_impl(an_alias, meth)
       else
         add_to(@aliases, an_alias)
+        unmatched_alias_list = @unmatched_alias_lists[an_alias.old_name] ||= []
+        unmatched_alias_list.push(an_alias)
       end
 
       an_alias
@@ -392,6 +409,10 @@ module RDoc
       @requires    = []
       @includes    = []
       @constants   = []
+
+      # This Hash maps a method name to a list of unmatched
+      # aliases (aliases of a method not yet encountered).
+      @unmatched_alias_lists = {}
     end
 
     # and remove classes and modules when we see a :nodoc: all
@@ -609,9 +630,18 @@ module RDoc
 
         cls = all[name]
 
-        unless cls then
+        if !cls then
           cls = class_type.new name, superclass
           all[name] = cls unless @done_documenting
+        else
+          # If the class has been encountered already, check that its
+          # superclass has been set (it may not have been, depending on
+          # the context in which it was encountered).
+          if class_type == NormalClass
+            if !cls.superclass then
+              cls.superclass = superclass
+            end
+          end
         end
 
         collection[name] = cls unless @done_documenting

data/lib/rdoc/generator/html/html.rb

@@ -37,6 +37,7 @@ body {
   margin-left: 40px;
   padding: 0;
   background: white;
+  color: black;
 }
 
 h1, h2, h3, h4 {

data/lib/rdoc/generator/texinfo/class.texinfo.erb

@@ -38,7 +38,7 @@ Methods
 <%       (method_list["methods"] || []).uniq.each do |method| %>
 <%=        TexinfoTemplate.new(@v.merge({'method' => method, 'list' => method_list}),
                                'method.texinfo.erb').render %><% end %>
-<%     end # section["method_list"] %>
-<%   end %>
+<%       end %>
+<%     end # if section["method_list"] %>
 <% end # @v['class']["sections"] %>
 <% end %>

data/lib/rdoc/markup/to_html_crossref.rb

@@ -65,7 +65,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
                       # The key thing is that there must be at least
                       # one special character (period, slash, or
                       # underscore).
-                      | \w+[_\/\.][\w\/\.]+
+                      | [\/\w]+[_\/\.][\w\/\.]+
 
                       # Things that have markup suppressed
                       | \\[^\s]

data/lib/rdoc/options.rb

@@ -184,7 +184,7 @@ class RDoc::Options
     @css = nil
     @webcvs = nil
 
-    @charset = 'iso-8859-1'
+    @charset = 'utf-8'
   end
 
   ##
@@ -196,6 +196,7 @@ class RDoc::Options
     opts = OptionParser.new do |opt|
       opt.program_name = File.basename $0
       opt.version = RDoc::VERSION
+      opt.release = nil
       opt.summary_indent = ' ' * 4
       opt.banner = <<-EOF
 Usage: #{opt.program_name} [options] [names...]
@@ -257,7 +258,7 @@ Usage: #{opt.program_name} [options] [names...]
       opt.separator nil
 
       opt.on("--charset=CHARSET", "-c",
-             "Specifies the HTML character-set.") do |value|
+             "Specifies the output HTML character-set.") do |value|
         @charset = value
       end
 
@@ -283,9 +284,7 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.on("--exclude=PATTERN", "-x", Regexp,
              "Do not process files or directories",
-             "matching PATTERN. Files given explicitly",
-             "on the command line will never be",
-             "excluded.") do |value|
+             "matching PATTERN.") do |value|
         @exclude << value
       end
 

data/lib/rdoc/parser.rb

@@ -76,7 +76,7 @@ class RDoc::Parser
   # Return a parser that can handle a particular extension
 
   def self.can_parse(file_name)
-    parser = RDoc::Parser.parsers.find { |regexp, parser| regexp =~ file_name }.last
+    parser = RDoc::Parser.parsers.find { |regexp,| regexp =~ file_name }.last
 
     #
     # The default parser should *NOT* parse binary files.

data/lib/rdoc/parser/c.rb

@@ -120,7 +120,7 @@ class RDoc::Parser::C < RDoc::Parser
 
       @stats.add_alias as
     end
- end
+  end
 
   def do_classes
     @content.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do 
@@ -155,7 +155,7 @@ class RDoc::Parser::C < RDoc::Parser
               \(
                  \s*(\w+),
                  \s*"(\w+)",
-                 \s*(\w+)\s*
+                 \s*([\w\*\s\(\)\.\->]+)\s*  # for SWIG
               \s*\)/mx) do |var_name, in_module, class_name, parent|
       handle_class_module(var_name, "class", class_name, parent, in_module)
     end
@@ -251,7 +251,7 @@ class RDoc::Parser::C < RDoc::Parser
       handle_method("method", "rb_mFileTest", meth_name, meth_body, param_count)
       handle_method("singleton_method", "rb_cFile", meth_name, meth_body, param_count)
     end
- end
+  end
 
   def find_attr_comment(attr_name)
     if @content =~ %r{((?>/\*.*?\*/\s+))
@@ -267,9 +267,9 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Find the C code corresponding to a Ruby method
 
-  def find_body(meth_name, meth_obj, body, quiet = false)
+  def find_body(class_name, meth_name, meth_obj, body, quiet = false)
     case body
-    when %r"((?>/\*.*?\*/\s*))(?:static\s+)?VALUE\s+#{meth_name}
+    when %r"((?>/\*.*?\*/\s*)*)(?:(?:static|SWIGINTERN)\s+)?(?:intern\s+)?VALUE\s+#{meth_name}
             \s*(\([^)]*\))([^;]|$)"xm
       comment, params = $1, $2
       body_text = $&
@@ -287,7 +287,7 @@ class RDoc::Parser::C < RDoc::Parser
       # distinct (for example Kernel.hash and Kernel.object_id share the same
       # implementation
 
-      override_comment = find_override_comment(meth_obj.name)
+      override_comment = find_override_comment(class_name, meth_obj.name)
       comment = override_comment if override_comment
 
       find_modifiers(comment, meth_obj) if comment
@@ -298,18 +298,18 @@ class RDoc::Parser::C < RDoc::Parser
       meth_obj.comment = mangle_comment(comment)
     when %r{((?>/\*.*?\*/\s*))^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m
       comment = $1
-      find_body($2, meth_obj, body, true)
+      find_body(class_name, $2, meth_obj, body, true)
       find_modifiers(comment, meth_obj)
       meth_obj.comment = mangle_comment(comment) + meth_obj.comment
     when %r{^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m
-      unless find_body($1, meth_obj, body, true)
+      unless find_body(class_name, $1, meth_obj, body, true)
         warn "No definition for #{meth_name}" unless @options.quiet
         return false
       end
     else
 
       # No body, but might still have an override comment
-      comment = find_override_comment(meth_obj.name)
+      comment = find_override_comment(class_name, meth_obj.name)
 
       if comment
         find_modifiers(comment, meth_obj)
@@ -365,10 +365,10 @@ class RDoc::Parser::C < RDoc::Parser
   def find_class_comment(class_name, class_meth)
     comment = nil
     if @content =~ %r{((?>/\*.*?\*/\s+))
-                   (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi
+                   (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi then
+      comment = $1
+    elsif @content =~ %r{Document-(?:class|module):\s#{class_name}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m
       comment = $1
-    elsif @content =~ %r{Document-(class|module):\s#{class_name}\s*?\n((?>.*?\*/))}m
-      comment = $2
     else
       if @content =~ /rb_define_(class|module)/m then
         class_name = class_name.split("::").last
@@ -422,9 +422,11 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
-  def find_override_comment(meth_name)
+  def find_override_comment(class_name, meth_name)
     name = Regexp.escape(meth_name)
-    if @content =~ %r{Document-method:\s#{name}\s*?\n((?>.*?\*/))}m
+    if @content =~ %r{Document-method:\s+#{class_name}(?:\.|::)#{name}\s*?\n((?>.*?\*/))}m then
+      $1
+    elsif @content =~ %r{Document-method:\s#{name}\s*?\n((?>.*?\*/))}m then
       $1
     end
   end
@@ -478,6 +480,10 @@ class RDoc::Parser::C < RDoc::Parser
     end
 
     if class_mod == "class" then
+      full_name = enclosure.full_name.to_s + "::#{class_name}"
+      if @content =~ %r{Document-class:\s+#{full_name}\s*<\s+([:,\w]+)} then
+        parent_name = $1
+      end
       cm = enclosure.add_class RDoc::NormalClass, class_name, parent_name
       @stats.add_class cm
     else
@@ -588,7 +594,7 @@ class RDoc::Parser::C < RDoc::Parser
         body = @content
       end
 
-      if find_body(meth_body, meth_obj, body) and meth_obj.document_self then
+      if find_body(class_name, meth_body, meth_obj, body) and meth_obj.document_self then
         class_obj.add_method meth_obj
         @stats.add_method meth_obj
       end

data/lib/rdoc/parser/perl.rb

@@ -0,0 +1,165 @@
+require 'rdoc/parser'
+
+##
+#
+# This is an attamept to write a basic parser for Perl's
+# POD (Plain old Documentation) format.  Ruby code must
+# co-exist with Perl, and some tasks are easier in Perl
+# than Ruby because of existing libraries.
+#
+# One difficult is that Perl POD has no means of identifying
+# the classes (packages) and methods (subs) with which it
+# is associated, it is more like literate programming in so
+# far as it just happens to be in the same place as the code,
+# but need not be.
+#
+# We would like to support all the markup the POD provides
+# so that it will convert happily to HTML.  At the moment
+# I don't think I can do that: time constraints. 
+#
+
+class RDoc::Parser::PerlPOD < RDoc::Parser
+
+  parse_files_matching(/.p[lm]$/)
+
+  ##
+  # Prepare to parse a perl file
+
+  def initialize(top_level, file_name, content, options, stats)
+    super
+
+    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
+
+    preprocess.handle @content do |directive, param|
+      warn "Unrecognized directive '#{directive}' in #{@file_name}"
+    end
+  end
+
+  ##
+  # Extract the Pod(-like) comments from the code.
+  # At its most basic there will ne no need to distinguish
+  # between the different types of header, etc.
+  #
+  # This uses a simple finite state machine, in a very
+  # procedural pattern. I could "replace case with polymorphism"
+  # but I think it would obscure the intent, scatter the
+  # code all over tha place.  This machine is necessary
+  # because POD requires that directives be preceded by
+  # blank lines, so reading line by line is necessary, 
+  # and preserving state about what is seen is necesary.
+
+  def scan
+
+    @top_level.comment ||= ""
+    state=:code_blank    
+    line_number = 0
+    line = nil
+
+    # This started out as a really long nested case statement,
+    # which also led to repetitive code.  I'd like to avoid that
+    # so I'm using a "table" instead.
+    
+    # Firstly we need some procs to do the transition and processing
+    # work.  Because these are procs they are closures, and they can
+    # use variables in the local scope.
+    #
+    # First, the "nothing to see here" stuff.
+    code_noop = lambda do 
+      if line =~ /^\s+$/
+	state = :code_blank
+      end
+    end
+
+    pod_noop = lambda do 
+      if line =~ /^\s+$/
+	state = :pod_blank
+      end
+      @top_level.comment += filter(line)
+    end
+
+    begin_noop = lambda do 
+      if line =~ /^\s+$/
+	state = :begin_blank
+      end
+      @top_level.comment += filter(line)
+    end
+
+    # Now for the blocks that process code and comments...
+
+    transit_to_pod = lambda do
+      case line
+      when /^=(?:pod|head\d+)/
+	state = :pod_no_blank
+	@top_level.comment += filter(line)
+      when /^=over/
+	state = :over_no_blank
+	@top_level.comment += filter(line)
+      when /^=(?:begin|for)/
+	state = :begin_no_blank
+      end
+    end
+
+    process_pod = lambda do
+      case line
+      when  /^\s*$/
+	state = :pod_blank
+	@top_level.comment += filter(line)
+      when /^=cut/
+	state = :code_no_blank
+      when /^=end/
+	$stderr.puts "'=end' unexpected at #{line_number} in #{@file_name}"
+      else
+	@top_level.comment += filter(line)
+      end
+    end
+
+
+    process_begin = lambda do
+      case line
+      when  /^\s*$/
+	state = :begin_blank
+	@top_level.comment += filter(line)
+      when /^=end/
+	state = :code_no_blank
+      when /^=cut/
+	$stderr.puts "'=cut' unexpected at #{line_number} in #{@file_name}"
+      else
+	@top_level.comment += filter(line)
+      end
+
+    end
+
+
+    transitions = { :code_no_blank => code_noop,
+                    :code_blank => transit_to_pod,
+		    :pod_no_blank => pod_noop,
+		    :pod_blank => process_pod,
+		    :begin_no_blank => begin_noop,
+		    :begin_blank => process_begin}
+    @content.each_line do |l|
+      line = l
+      line_number += 1
+      transitions[state].call
+    end # each line
+
+    @top_level
+  end
+
+  # Filter the perl markup that does the same as the rdoc
+  # filtering.  Only basic for now. Will probably need a
+  # proper parser to cope with C<<...>> etc
+  def filter(comment)
+    return '' if comment =~ /^=pod\s*$/
+    comment.gsub!(/^=pod/, '==')
+    comment.gsub!(/^=head(\d+)/) do 
+      "=" * $1.to_i
+    end
+    comment.gsub!(/=item/, '');
+    comment.gsub!(/C<(.*?)>/, '<tt>\1</tt>');
+    comment.gsub!(/I<(.*?)>/, '<i>\1</i>');
+    comment.gsub!(/B<(.*?)>/, '<b>\1</b>');
+    comment
+  end
+
+end
+

data/lib/rdoc/parser/ruby.rb

@@ -1945,9 +1945,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
         case tk
         when TkSEMICOLON
           break
-        when TkLPAREN, TkfLPAREN
+        when TkLPAREN, TkfLPAREN, TkLBRACE, TkLBRACK, TkDO
           nest += 1
-        when TkRPAREN
+        when TkRPAREN, TkRBRACE, TkRBRACK, TkEND
           nest -= 1
         when TkCOMMENT
           if nest <= 0 && @scanner.lex_state == EXPR_END
@@ -1955,7 +1955,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
             break
           end
         when TkNL
-          if (@scanner.lex_state == EXPR_END and nest <= 0) || !@scanner.continue
+          if (nest <= 0) && ((@scanner.lex_state == EXPR_END) || (!@scanner.continue))
             unget_tk(tk)
             break
           end

data/lib/rdoc/rdoc.rb

@@ -7,6 +7,7 @@ require 'rdoc/parser/simple'
 require 'rdoc/parser/ruby'
 require 'rdoc/parser/c'
 require 'rdoc/parser/f95'
+require 'rdoc/parser/perl'
 
 require 'rdoc/stats'
 require 'rdoc/options'
@@ -189,11 +190,11 @@ module RDoc
 
     def parse_files(options)
       @stats = Stats.new options.verbosity
-      
+
       files = options.files
       files = ["."] if files.empty?
 
-      file_list = normalized_file_list(options, files, true)
+      file_list = normalized_file_list(options, files, true, options.exclude)
 
       return [] if file_list.empty?
 

data/lib/rdoc/ri/display.rb

@@ -86,21 +86,19 @@ class RDoc::RI::DefaultDisplay
         constants = klass.constants.sort_by { |constant| constant.name }
 
         constants.each do |constant|
+          @formatter.wrap "#{constant.name} = #{constant.value}"
           if constant.comment then
-            @formatter.wrap "#{constant.name}:"
-
             @formatter.indent do
               @formatter.display_flow constant.comment
             end
           else
-            @formatter.wrap constant.name
+            @formatter.break_to_newline
           end
         end
       end
 
       unless klass.attributes.empty? then
         @formatter.blankline
-
         @formatter.display_heading 'Attributes:', 2, ''
 
         attributes = klass.attributes.sort_by { |attribute| attribute.name }
@@ -113,6 +111,7 @@ class RDoc::RI::DefaultDisplay
             end
           else
             @formatter.wrap "#{attribute.name} (#{attribute.rw})"
+            @formatter.break_to_newline
           end
         end
       end

data/lib/rdoc/ri/driver.rb

@@ -77,14 +77,12 @@ class RDoc::RI::Driver
 
   attr_accessor :homepath # :nodoc:
 
-  def self.process_args(argv)
+  def self.default_options
     options = {}
     options[:use_stdout] = !$stdout.tty?
     options[:width] = 72
     options[:formatter] = RDoc::RI::Formatter.for 'plain'
     options[:interactive] = false
-    options[:list_classes] = false
-    options[:list_names] = false
     options[:use_cache] = true
 
     # By default all standard paths are used.
@@ -94,9 +92,16 @@ class RDoc::RI::Driver
     options[:use_gems] = true
     options[:extra_doc_dirs] = []
 
+    return options
+  end
+
+  def self.process_args(argv)
+    options = default_options
+
     opts = OptionParser.new do |opt|
       opt.program_name = File.basename $0
       opt.version = RDoc::VERSION
+      opt.release = nil
       opt.summary_indent = ' ' * 4
 
       directories = [
@@ -151,14 +156,6 @@ Options may also be set in the 'RI' environment variable.
       opt.separator "Options:"
       opt.separator nil
 
-      opt.on("--classes", "-c",
-             "Display the names of classes and modules we",
-             "know about.") do |value|
-        options[:list_classes] = value
-      end
-
-      opt.separator nil
-
       opt.on("--fmt=FORMAT", "--format=FORMAT", "-f",
              RDoc::RI::Formatter::FORMATTERS.keys,
              "Format to use when displaying output:",
@@ -251,14 +248,6 @@ Options may also be set in the 'RI' environment variable.
 
       opt.separator nil
 
-      opt.on("--list-names", "-l",
-             "List all the names known to RDoc, one per",
-             "line.") do
-        options[:list_names] = true
-      end
-
-      opt.separator nil
-
       opt.on("--no-pager", "-T",
              "Send output directly to stdout,",
              "rather than to a pager.") do
@@ -311,9 +300,10 @@ Options may also be set in the 'RI' environment variable.
     ri.run
   end
 
-  def initialize(options={})
-    @names = options[:names]
+  def initialize(initial_options={})
+    options = self.class.default_options.update(initial_options)
 
+    @names = options[:names]
     @class_cache_name = 'classes'
 
     @doc_dirs = RDoc::RI::Paths.path(options[:use_system],
@@ -380,7 +370,7 @@ Options may also be set in the 'RI' environment variable.
     else
       @class_cache = create_class_cache
     end
-    
+
     @class_cache
   end
 
@@ -513,7 +503,7 @@ Options may also be set in the 'RI' environment variable.
         cache[name] = method
       end
     end
-    
+
     write_cache cache, path
   end
 
@@ -521,6 +511,15 @@ Options may also be set in the 'RI' environment variable.
   # Finds the next ancestor of +orig_klass+ after +klass+.
 
   def lookup_ancestor(klass, orig_klass)
+    # This is a bit hacky, but ri will go into an infinite
+    # loop otherwise, since Object has an Object ancestor
+    # for some reason.  Depending on the documentation state, I've seen
+    # Kernel as an ancestor of Object and not as an ancestor of Object.
+    if ((orig_klass == "Object") &&
+        ((klass == "Kernel") || (klass == "Object")))
+      return nil
+    end
+
     cache = class_cache[orig_klass]
 
     return nil unless cache
@@ -528,10 +527,13 @@ Options may also be set in the 'RI' environment variable.
     ancestors = [orig_klass]
     ancestors.push(*cache.includes.map { |inc| inc['name'] })
     ancestors << cache.superclass
+    
+    ancestor_index = ancestors.index(klass)
 
-    ancestor = ancestors[ancestors.index(klass) + 1]
-
-    return ancestor if ancestor
+    if ancestor_index
+      ancestor = ancestors[ancestors.index(klass) + 1]
+      return ancestor if ancestor
+    end
 
     lookup_ancestor klass, cache.superclass
   end
@@ -551,7 +553,7 @@ Options may also be set in the 'RI' environment variable.
   def map_dirs(file_name)
     @doc_dirs.map { |dir| yield File.join(dir, file_name) }.flatten.compact
   end
-  
+
   ##
   # Extract the class and method name parts from +name+ like Foo::Bar#baz
 
@@ -598,29 +600,29 @@ Options may also be set in the 'RI' environment variable.
           end
         elsif name =~ /::|\#|\./ then
           klass, = parse_name name
-          
+
           orig_klass = klass
           orig_name = name
-          
+
           loop do
             method = lookup_method name, klass
-            
+
             break method if method
-            
+
             ancestor = lookup_ancestor klass, orig_klass
-            
+
             break unless ancestor
-            
+
             name = name.sub klass, ancestor
             klass = ancestor
           end
-          
+
           raise NotFoundError, orig_name unless method
-          
+
           display_method method
         else
           methods = select_methods(/#{name}/)
-          
+
           if methods.size == 0
             raise NotFoundError, name
           elsif methods.size == 1
@@ -660,7 +662,7 @@ Options may also be set in the 'RI' environment variable.
         Marshal.dump cache, cache_file
       end
     end
-      
+
     cache
   end
 

data/test/test_rdoc_markup_to_html_crossref.rb

@@ -127,7 +127,8 @@ class TestRDocMarkupToHtmlCrossref < Test::Unit::TestCase
   # file_name (String) for String reference.
   #
   def verify_file_crossref(xref, reference, file_name)
-    result = "<a href=\"../files/#{file_name.gsub(/\./, '_')}.html\">#{reference}</a>"
+    generated_document_path = Pathname.new("../files/#{file_name.gsub(/\./, '_')}.html").cleanpath.to_s
+    result = "<a href=\"#{generated_document_path}\">#{reference}</a>"
 
     verify_convert xref, reference, result
   end

data/test/test_rdoc_parser_c.rb

@@ -244,9 +244,36 @@ Init_Foo(void) {
     assert_equal "  \n   a comment for class Foo on Init\n   \n", klass.comment
   end
 
+  def test_define_method
+    content = <<-EOF
+/*Method Comment! */
+static VALUE
+rb_io_s_read(argc, argv, io)
+    int argc;
+    VALUE *argv;
+    VALUE io;
+{
+}
+
+void
+Init_IO(void) {
+    /*
+     * a comment for class Foo on rb_define_class
+     */
+    VALUE rb_cIO = rb_define_class("IO", rb_cObject);
+    rb_define_singleton_method(rb_cIO, "read", rb_io_s_read, -1);
+}
+    EOF
+
+    klass = util_get_class content, 'rb_cIO'
+    read_method = klass.method_list.first
+    assert_equal "read", read_method.name
+    assert_equal "  Method Comment!   \n", read_method.comment
+  end
+
   def util_get_class(content, name)
     parser = util_parser content
-    parser.do_classes
+    parser.scan
     parser.classes[name]
   end
 

data/test/test_rdoc_parser_perl.rb

@@ -0,0 +1,72 @@
+require 'stringio'
+require 'tempfile'
+require 'test/unit'
+require 'rdoc/options'
+require 'rdoc/parser/perl'
+
+class TestRdocParserPerlPOD < Test::Unit::TestCase
+
+  def setup
+    @tempfile = Tempfile.new self.class.name
+    filename = @tempfile.path
+
+    @top_level = RDoc::TopLevel.new filename
+    @fn = filename
+    @options = RDoc::Options.new
+    @stats = RDoc::Stats.new 0
+  end
+
+  def teardown
+    @tempfile.close
+  end
+
+  def test_uncommented_perl
+    content = <<-EOF
+while (<>) {
+  tr/a-z/A-Z;
+  print
+}
+    EOF
+
+    comment =  util_get_comment content
+    assert_equal "", comment
+  end
+
+  def test_perl_without_pod
+    content = <<-EOF
+#!/usr/local/bin/perl
+#
+#This is a pointless perl program because it does -p.
+#
+while(<>) {print;}:
+    EOF
+
+    comment = util_get_comment content
+    assert_equal "", comment
+  end
+
+  def test_simple_pod_no_structure
+    content = <<-EOF
+=begin pod
+
+This just contains plain old documentation
+
+=end
+    EOF
+    comment = util_get_comment content
+    assert_equal "\nThis just contains plain old documentation\n\n", comment
+  end
+
+  # Get the comment of the @top_level when it has processed the input.
+  def util_get_comment(content)
+    parser = util_parser content
+    parser.scan.comment
+  end
+
+  # create a new parser with the supplied content.
+  def util_parser(content)
+    RDoc::Parser::PerlPOD.new @top_level, @fn, content, @options, @stats
+  end
+
+end
+

data/test/test_rdoc_parser_ruby.rb

@@ -12,6 +12,10 @@ class TestRDocParserRuby < Test::Unit::TestCase
     @tempfile = Tempfile.new self.class.name
     @filename = @tempfile.path
 
+    # Some tests need two paths.
+    @tempfile2 = Tempfile.new self.class.name
+    @filename2 = @tempfile2.path
+
     util_toplevel
     @options = RDoc::Options.new
     @options.quiet = true
@@ -20,6 +24,7 @@ class TestRDocParserRuby < Test::Unit::TestCase
 
   def teardown
     @tempfile.unlink
+    @tempfile2.unlink
   end
 
   def test_look_for_directives_in_commented
@@ -204,6 +209,34 @@ EOF
     assert_equal 'Foo::Baz', baz.full_name
   end
 
+  def test_parse_class_definition_encountered_after_class_reference
+#
+# The code below is not strictly legal Ruby (Foo must have been defined
+# before Foo.bar is encountered), but RDoc might encounter Foo.bar before
+# Foo if they live in different files.
+#
+    code = <<-EOF
+def Foo.bar
+end
+
+class Foo < IO
+end
+EOF
+
+    util_parser code
+
+    @parser.scan()
+
+    assert(@top_level.modules.empty?)
+
+    foo = @top_level.classes.first
+    assert_equal 'Foo', foo.full_name
+    assert_equal 'IO', foo.superclass
+
+    bar = foo.method_list.first
+    assert_equal 'bar', bar.name
+  end
+
   def test_parse_module_relative_to_top_level_namespace
     comment = <<-EOF
 #
@@ -487,9 +520,107 @@ end
 
     @parser.parse_statements @top_level, RDoc::Parser::Ruby::NORMAL, nil, ''
 
+    foo = @top_level.classes.first.method_list[0]
+    assert_equal 'foo', foo.name
+
     foo2 = @top_level.classes.first.method_list.last
     assert_equal 'foo2', foo2.name
     assert_equal 'foo', foo2.is_alias_for.name
+    assert @top_level.classes.first.aliases.empty?
+  end
+
+  def test_parse_statements_identifier_alias_method_before_original_method
+    # This is not strictly legal Ruby code, but it simulates finding an alias
+    # for a method before finding the original method, which might happen
+    # to rdoc if the alias is in a different file than the original method
+    # and rdoc processes the alias' file first.
+    content = <<-EOF
+class Foo
+  alias_method :foo2, :foo
+
+  alias_method :foo3, :foo
+
+  def foo()
+  end
+
+  alias_method :foo4, :foo
+
+  alias_method :foo5, :unknown
+end
+EOF
+
+    util_parser content
+
+    @parser.parse_statements @top_level, RDoc::Parser::Ruby::NORMAL, nil, ''
+
+    foo = @top_level.classes.first.method_list[0]
+    assert_equal 'foo', foo.name
+
+    foo2 = @top_level.classes.first.method_list[1]
+    assert_equal 'foo2', foo2.name
+    assert_equal 'foo', foo2.is_alias_for.name
+
+    foo3 = @top_level.classes.first.method_list[2]
+    assert_equal 'foo3', foo3.name
+    assert_equal 'foo', foo3.is_alias_for.name
+
+    foo4 = @top_level.classes.first.method_list.last
+    assert_equal 'foo4', foo4.name
+    assert_equal 'foo', foo4.is_alias_for.name
+
+    assert_equal 'unknown', @top_level.classes.first.aliases[0].old_name
+  end
+
+  def test_parse_statements_identifier_constant
+    content = <<-EOF
+class Foo
+  FIRST_CONSTANT = 5
+
+  SECOND_CONSTANT = [
+     1,
+     2,
+     3
+  ]
+
+  THIRD_CONSTANT = {
+     :foo => 'bar',
+     :x => 'y'
+  }
+
+  FOURTH_CONSTANT = SECOND_CONSTANT.map do |element|
+    element + 1
+    element + 2
+  end
+
+  FIFTH_CONSTANT = SECOND_CONSTANT.map { |element| element + 1 }
+end
+EOF
+
+    util_parser content
+
+    @parser.parse_statements @top_level, RDoc::Parser::Ruby::NORMAL, nil, ''
+
+    constants = @top_level.classes.first.constants
+
+    constant = constants[0]
+    assert_equal 'FIRST_CONSTANT', constant.name
+    assert_equal '5', constant.value
+
+    constant = constants[1]
+    assert_equal 'SECOND_CONSTANT', constant.name
+    assert_equal '[      1,      2,      3   ]', constant.value
+
+    constant = constants[2]
+    assert_equal 'THIRD_CONSTANT', constant.name
+    assert_equal "{      :foo => 'bar',      :x => 'y'   }", constant.value
+
+    constant = constants[3]
+    assert_equal 'FOURTH_CONSTANT', constant.name
+    assert_equal 'SECOND_CONSTANT.map do |element|     element + 1     element + 2   end', constant.value
+
+    constant = constants.last
+    assert_equal 'FIFTH_CONSTANT', constant.name
+    assert_equal 'SECOND_CONSTANT.map { |element| element + 1 }', constant.value
   end
 
   def test_parse_statements_identifier_attr
@@ -601,9 +732,17 @@ end
                                      @stats
   end
 
+  def util_two_parsers(first_file_content, second_file_content)
+    util_parser first_file_content
+
+    @parser2 = RDoc::Parser::Ruby.new @top_level2, @filename,
+                                      second_file_content, @options, @stats
+  end
+
   def util_toplevel
     RDoc::TopLevel.reset
     @top_level = RDoc::TopLevel.new @filename
+    @top_level2 = RDoc::TopLevel.new @filename2
   end
 
 end

data/test/test_rdoc_ri_default_display.rb

@@ -42,9 +42,9 @@ class TestRDocRiDefaultDisplay < Test::Unit::TestCase
       ],
       'comment' => [RDoc::Markup::Flow::P.new('SomeClass comment')],
       'constants' => [
-        { 'name' => 'CONSTANT', 'value' => '"value"',
+        { 'name' => 'CONSTANT', 'value' => '"value1"',
           'comment' => [RDoc::Markup::Flow::P.new('CONSTANT value')] },
-        { 'name' => 'CONSTANT_NOCOMMENT', 'value' => '"value"',
+        { 'name' => 'CONSTANT_NOCOMMENT', 'value' => '"value2"',
           'comment' => nil },
       ],
       'display_name' => 'Class',
@@ -70,10 +70,10 @@ class TestRDocRiDefaultDisplay < Test::Unit::TestCase
 Constants:
 ----------
 
-     CONSTANT:
+     CONSTANT = "value1"
           CONSTANT value
 
-     CONSTANT_NOCOMMENT
+     CONSTANT_NOCOMMENT = "value2"
 
 
 Attributes:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rdoc
 version: !ruby/object:Gem::Version 
-  version: 2.2.0
+  version: 2.2.1
 platform: ruby
 authors: 
 - Eric Hodel
@@ -12,7 +12,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-19 00:00:00 -04:00
+date: 2008-09-24 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -91,6 +91,7 @@ files:
 - lib/rdoc/parser.rb
 - lib/rdoc/parser/c.rb
 - lib/rdoc/parser/f95.rb
+- lib/rdoc/parser/perl.rb
 - lib/rdoc/parser/ruby.rb
 - lib/rdoc/parser/simple.rb
 - lib/rdoc/rdoc.rb
@@ -117,6 +118,7 @@ files:
 - test/test_rdoc_markup_to_html_crossref.rb
 - test/test_rdoc_parser.rb
 - test/test_rdoc_parser_c.rb
+- test/test_rdoc_parser_perl.rb
 - test/test_rdoc_parser_ruby.rb
 - test/test_rdoc_ri_attribute_formatter.rb
 - test/test_rdoc_ri_default_display.rb
@@ -157,6 +159,7 @@ test_files:
 - test/test_rdoc_markup_to_html_crossref.rb
 - test/test_rdoc_info_sections.rb
 - test/test_rdoc_ri_formatter.rb
+- test/test_rdoc_parser_perl.rb
 - test/test_rdoc_ri_driver.rb
 - test/test_attribute_manager.rb
 - test/test_rdoc_parser_ruby.rb