rdoc 2.0.0 → 2.1.0

data.tar.gz.sig

@@ -0,0 +1 @@
+U�����5j�_Bf~M�]�h煆�_����-G}�tk��C�{�
6)��6XGÆ���|�����KE��~þ{>�va���RV����B,�0JA��
Kw|ީ7�4�}�P��

data/History.txt

@@ -1,3 +1,33 @@
+=== 2.1.0 / ??
+
+* 3 Major Enhancements:
+  * RDoc now knows about meta-programmed methods, see RDoc::Parser::Ruby
+  * Reorganized parsers under RDoc::Parser base class
+  * ri now walks the ancestors of a class looking for a method e.g. ri
+    File#read displays documentation for IO#read (may require regeneration of
+    ri data)
+* 5 Minor Enhancements:
+  * Allow links to files
+  * Default options now taken from RDOCOPT environment variable
+  * Class method documentation can be found at toplevel now (def X.foo)
+  * Allow HTML templates distributed as gems to be loaded with the -T option,
+    just like the standard templates in rdoc/generator/html (so an HTML
+    template lib/new_template.rb in a gem can be used with rdoc -T new_template)
+  * `rdoc -v` prints out files, classes, modules and methods as it goes
+* 11 Bug Fixes:
+  * `ri Foo.bar` now looks for class methods also
+  * Sections work in the default template again
+  * Doesn't warn about :foo:: list item being an unrecognized directive
+  * RDoc no longer converts characters inside tt tags
+  * Fixed "unitialized constant RDoc::Markup::ToHtml::HTML"
+  * Fixed generation of relative links
+  * Fixed various diagram generation issues
+  * Fixed templates broken by switch to erb
+  * Fixed issue with <!-- --> style comments
+  * Lowercase words are no longer rdoc'd as methods without leading #, as
+    described in the documentation
+  * RDoc now correctly sets superclasses if they were originally unknown
+
 === 2.0.0 / 2008-04-10
 
 * 3 Major Enhancements:

data/Manifest.txt

@@ -12,14 +12,21 @@ lib/rdoc/generator.rb
 lib/rdoc/generator/chm.rb
 lib/rdoc/generator/chm/chm.rb
 lib/rdoc/generator/html.rb
+lib/rdoc/generator/html/frameless.rb
 lib/rdoc/generator/html/hefss.rb
 lib/rdoc/generator/html/html.rb
 lib/rdoc/generator/html/kilmer.rb
 lib/rdoc/generator/html/one_page_html.rb
 lib/rdoc/generator/ri.rb
+lib/rdoc/generator/texinfo.rb
+lib/rdoc/generator/texinfo/class.texinfo.erb
+lib/rdoc/generator/texinfo/file.texinfo.erb
+lib/rdoc/generator/texinfo/method.texinfo.erb
+lib/rdoc/generator/texinfo/texinfo.erb
 lib/rdoc/generator/xml.rb
 lib/rdoc/generator/xml/rdf.rb
 lib/rdoc/generator/xml/xml.rb
+lib/rdoc/known_classes.rb
 lib/rdoc/markup.rb
 lib/rdoc/markup/attribute_manager.rb
 lib/rdoc/markup/formatter.rb
@@ -32,12 +39,13 @@ lib/rdoc/markup/to_html.rb
 lib/rdoc/markup/to_html_crossref.rb
 lib/rdoc/markup/to_latex.rb
 lib/rdoc/markup/to_test.rb
+lib/rdoc/markup/to_texinfo.rb
 lib/rdoc/options.rb
-lib/rdoc/parsers/parse_c.rb
-lib/rdoc/parsers/parse_f95.rb
-lib/rdoc/parsers/parse_rb.rb
-lib/rdoc/parsers/parse_simple.rb
-lib/rdoc/parsers/parserfactory.rb
+lib/rdoc/parser.rb
+lib/rdoc/parser/c.rb
+lib/rdoc/parser/f95.rb
+lib/rdoc/parser/ruby.rb
+lib/rdoc/parser/simple.rb
 lib/rdoc/rdoc.rb
 lib/rdoc/ri.rb
 lib/rdoc/ri/cache.rb
@@ -52,10 +60,14 @@ lib/rdoc/ri/writer.rb
 lib/rdoc/stats.rb
 lib/rdoc/template.rb
 lib/rdoc/tokenstream.rb
-test/test_rdoc_c_parser.rb
+test/test_rdoc_info_formatting.rb
+test/test_rdoc_info_sections.rb
 test/test_rdoc_markup.rb
 test/test_rdoc_markup_attribute_manager.rb
+test/test_rdoc_parser_c.rb
+test/test_rdoc_parser_ruby.rb
 test/test_rdoc_ri_attribute_formatter.rb
 test/test_rdoc_ri_default_display.rb
+test/test_rdoc_ri_driver.rb
 test/test_rdoc_ri_formatter.rb
 test/test_rdoc_ri_overstrike_formatter.rb

data/Rakefile

@@ -6,5 +6,57 @@ require 'rdoc'
 Hoe.new "rdoc", RDoc::VERSION do |rdoc|
   rdoc.developer 'Eric Hodel', 'drbrain@segment7.net'
   rdoc.developer 'Dave Thomas', ''
+  rdoc.developer 'Phil Hagelberg', 'technomancy@gmail.com'
+end
+
+# These tasks expect to have the following directory structure:
+#
+#   git/git.rubini.us/code # Rubinius git HEAD checkout
+#   svn/ruby/trunk         # ruby subversion HEAD checkout
+#   svn/rdoc/trunk         # RDoc subversion HEAD checkout
+#
+# If you don't have this directory structure, set RUBY_PATH and/or
+# RUBINIUS_PATH.
+
+diff_options = "-urpN --exclude '*svn*' --exclude '*swp' --exclude '*rbc'"
+rsync_options = "-avP --exclude '*svn*' --exclude '*swp' --exclude '*rbc' --exclude '*.rej' --exclude '*.orig'"
+
+rubinius_dir = ENV['RUBINIUS_PATH'] || '../../../git/git.rubini.us/code'
+ruby_dir = ENV['RUBY_PATH'] || '../../ruby/trunk'
+
+desc "Updates Ruby HEAD with the currently checked-out copy of RDoc."
+task :update_ruby do
+  sh "rsync #{rsync_options} bin/rdoc #{ruby_dir}/bin/rdoc"
+  sh "rsync #{rsync_options} bin/ri #{ruby_dir}/bin/ri"
+  sh "rsync #{rsync_options} lib/ #{ruby_dir}/lib"
+  sh "rsync #{rsync_options} test/ #{ruby_dir}/test/rdoc"
+end
+
+desc "Diffs Ruby HEAD with the currently checked-out copy of RDoc."
+task :diff_ruby do
+  options = "-urpN --exclude '*svn*' --exclude '*swp' --exclude '*rbc'"
+
+  sh "diff #{diff_options} bin/rdoc #{ruby_dir}/bin/rdoc; true"
+  sh "diff #{diff_options} bin/ri #{ruby_dir}/bin/ri; true"
+  sh "diff #{diff_options} lib/rdoc.rb #{ruby_dir}/lib/rdoc.rb; true"
+  sh "diff #{diff_options} lib/rdoc #{ruby_dir}/lib/rdoc; true"
+  sh "diff #{diff_options} test #{ruby_dir}/test/rdoc; true"
+end
+
+desc "Updates Rubinius HEAD with the currently checked-out copy of RDoc."
+task :update_rubinius do
+  sh "rsync #{rsync_options} bin/rdoc #{rubinius_dir}/lib/bin/rdoc.rb"
+  sh "rsync #{rsync_options} bin/ri #{rubinius_dir}/lib/bin/ri.rb"
+  sh "rsync #{rsync_options} lib/ #{rubinius_dir}/lib"
+  sh "rsync #{rsync_options} test/ #{rubinius_dir}/test/rdoc"
+end
+
+desc "Diffs Rubinius HEAD with the currently checked-out copy of RDoc."
+task :diff_rubinius do
+  sh "diff #{diff_options} bin/rdoc #{rubinius_dir}/lib/bin/rdoc.rb; true"
+  sh "diff #{diff_options} bin/ri #{rubinius_dir}/lib/bin/ri.rb; true"
+  sh "diff #{diff_options} lib/rdoc.rb #{rubinius_dir}/lib/rdoc.rb; true"
+  sh "diff #{diff_options} lib/rdoc #{rubinius_dir}/lib/rdoc; true"
+  sh "diff #{diff_options} test #{rubinius_dir}/test/rdoc; true"
 end
 

data/lib/rdoc.rb

@@ -1,8 +1,8 @@
 $DEBUG_RDOC = nil
 
 ##
-# = RDOC - Ruby Documentation System
-# 
+# RDoc - Ruby Documentation System
+#
 # This package contains RDoc and RDoc::Markup.  RDoc is an application that
 # produces documentation for one or more Ruby source files.  We work similarly
 # to JavaDoc, parsing the source, and extracting the definition for classes,
@@ -12,76 +12,76 @@ $DEBUG_RDOC = nil
 # RDoc::Markup is a library that converts plain text into various output
 # formats.  The markup library is used to interpret the comment blocks that
 # RDoc uses to document methods, classes, and so on.
-# 
+#
 # == Roadmap
-# 
+#
 # * If you want to use RDoc to create documentation for your Ruby source files,
 #   read on.
-# * If you want to include extensions written in C, see RDoc::C_Parser
+# * If you want to include extensions written in C, see RDoc::Parser::C
 # * For information on the various markups available in comment blocks, see
 #   RDoc::Markup.
-# * If you want to drive RDoc programatically, see RDoc::RDoc.
+# * If you want to drive RDoc programmatically, see RDoc::RDoc.
 # * If you want to use the library to format text blocks into HTML, have a look
 #   at RDoc::Markup.
 # * If you want to try writing your own HTML output template, see
 #   RDoc::Generator::HTML
-# 
+#
 # == Summary
-# 
+#
 # Once installed, you can create documentation using the 'rdoc' command
 # (the command is 'rdoc.bat' under Windows)
-# 
+#
 #   % rdoc [options] [names...]
-# 
+#
 # Type "rdoc --help" for an up-to-date option summary.
-# 
+#
 # A typical use might be to generate documentation for a package of Ruby
-# source (such as rdoc itself). 
-# 
+# source (such as rdoc itself).
+#
 #   % rdoc
-# 
+#
 # This command generates documentation for all the Ruby and C source
 # files in and below the current directory.  These will be stored in a
 # documentation tree starting in the subdirectory 'doc'.
-# 
+#
 # You can make this slightly more useful for your readers by having the
 # index page contain the documentation for the primary file.  In our
 # case, we could type
-# 
+#
 #   % rdoc --main rdoc.rb
-# 
+#
 # You'll find information on the various formatting tricks you can use
 # in comment blocks in the documentation this generates.
-# 
+#
 # RDoc uses file extensions to determine how to process each file.  File names
 # ending +.rb+ and <tt>.rbw</tt> are assumed to be Ruby source.  Files
 # ending +.c+ are parsed as C files.  All other files are assumed to
 # contain just Markup-style markup (with or without leading '#' comment
 # markers).  If directory names are passed to RDoc, they are scanned
 # recursively for C and Ruby source files only.
-# 
+#
 # = Markup
-# 
+#
 # For information on how to make lists, hyperlinks, etc. with RDoc, see
 # RDoc::Markup.
-# 
+#
 # Comment blocks can be written fairly naturally, either using '#' on
 # successive lines of the comment, or by including the comment in
 # an =begin/=end block.  If you use the latter form, the =begin line must be
 # flagged with an RDoc tag:
-# 
+#
 #   =begin rdoc
 #   Documentation to be processed by RDoc.
 #   
 #   ...
 #   =end
-# 
+#
 # RDoc stops processing comments if it finds a comment line containing
 # a <tt>--</tt>.  This can be used to separate external from internal
 # comments, or to stop a comment being associated with a method, class, or
 # module.  Commenting can be turned back on with a line that starts with a
 # <tt>++</tt>.
-# 
+#
 #   ##
 #   # Extract the age and calculate the date-of-birth.
 #   #--
@@ -92,40 +92,40 @@ $DEBUG_RDOC = nil
 #   def get_dob(person)
 #     # ...
 #   end
-# 
+#
 # Names of classes, source files, and any method names containing an
 # underscore or preceded by a hash character are automatically hyperlinked
-# from comment text to their description. 
-# 
+# from comment text to their description.
+#
 # Method parameter lists are extracted and displayed with the method
 # description.  If a method calls +yield+, then the parameters passed to yield
 # will also be displayed:
-# 
+#
 #   def fred
 #     ...
 #     yield line, address
-# 
+#
 # This will get documented as:
-# 
+#
 #   fred() { |line, address| ... }
-# 
+#
 # You can override this using a comment containing ':yields: ...' immediately
 # after the method definition
-# 
+#
 #   def fred # :yields: index, position
 #     # ...
 #   
 #     yield line, address
-# 
+#
 # which will get documented as
-# 
+#
 #    fred() { |index, position| ... }
-# 
+#
 # +:yields:+ is an example of a documentation directive.  These appear
 # immediately after the start of the document element they are modifying.
-# 
+#
 # == Directives
-# 
+#
 # [+:nodoc:+ / +:nodoc:+ all]
 #   Don't include this element in the documentation.  For classes
 #   and modules, the methods, aliases, constants, and attributes
@@ -143,27 +143,27 @@ $DEBUG_RDOC = nil
 #       class Output
 #       end
 #     end
-#   
-#   In the above code, only class +MyModule::Input+ will be documented.
-#   :nodoc: is global across all files the class or module appears in, so use
-#   :stopdoc:/:startdoc: to only omit documentation for a particular set of
-#   methods, etc.
-# 
+#
+#   In the above code, only class +MyModule::Input+ will be documented.The
+#   The :nodoc: directive is global across all files the class or module
+#   appears in, so use :stopdoc:/:startdoc: to only omit documentation for a
+#   particular set of methods, etc.
+#
 # [+:doc:+]
 #   Force a method or attribute to be documented even if it wouldn't otherwise
 #   be.  Useful if, for example, you want to include documentation of a
 #   particular private method.
-# 
+#
 # [+:notnew:+]
 #   Only applicable to the +initialize+ instance method.  Normally RDoc
-#   assumes   that the documentation and parameters for #initialize are
+#   assumes that the documentation and parameters for #initialize are
 #   actually for the ::new method, and so fakes out a ::new for the class.
 #   The :notnew: modifier stops this.  Remember that #initialize is protected,
 #   so you won't see the documentation unless you use the -a command line
 #   option.
-# 
+#
 # Comment blocks can contain other directives:
-# 
+#
 # [<tt>:section: title</tt>]
 #   Starts a new section in the output.  The title following +:section:+ is
 #   used as the section heading, and the remainder of the comment containing
@@ -178,66 +178,66 @@ $DEBUG_RDOC = nil
 #     # This is the section that I wrote.
 #     # See it glisten in the noon-day sun.
 #     # ----------------------------------------
-# 
+#
 # [+:call-seq:+]
 #   Lines up to the next blank line in the comment are treated as the method's
 #   calling sequence, overriding the default parsing of method parameters and
 #   yield arguments.
-# 
+#
 # [+:include:+ _filename_]
 #   \Include the contents of the named file at this point.  The file will be
 #   searched for in the directories listed by the +--include+ option, or in
 #   the current directory by default.  The contents of the file will be
-#   shifted to have the same indentation as the ':' at the start of the
-#   :include: directive.
-# 
+#   shifted to have the same indentation as the ':' at the start of
+#   the :include: directive.
+#
 # [+:title:+ _text_]
 #   Sets the title for the document.  Equivalent to the <tt>--title</tt>
 #   command line parameter.  (The command line parameter overrides any :title:
 #   directive in the source).
-# 
+#
 # [+:enddoc:+]
 #   Document nothing further at the current level.
-# 
+#
 # [+:main:+ _name_]
 #   Equivalent to the <tt>--main</tt> command line parameter.
-# 
+#
 # [+:stopdoc:+ / +:startdoc:+]
 #   Stop and start adding new documentation elements to the current container.
 #   For example, if a class has a number of constants that you don't want to
 #   document, put a +:stopdoc:+ before the first, and a +:startdoc:+ after the
-#   last.  If you don't specifiy a +:startdoc:+ by the end of the container,
+#   last.  If you don't specify a +:startdoc:+ by the end of the container,
 #   disables documentation for the entire class or module.
-# 
+#
 # = Other stuff
-# 
+#
 # RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>
 #
 # Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
-# 
+#
 # == Credits
-# 
+#
 # * The Ruby parser in rdoc/parse.rb is based heavily on the outstanding
 #   work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby
 #   parser for irb and the rtags package.
-# 
+#
 # * Code to diagram classes and modules was written by Sergey A Yanovitsky
 #   (Jah) of Enticla.
-# 
+#
 # * Charset patch from MoonWolf.
-# 
+#
 # * Rich Kilmer wrote the kilmer.rb output template.
-# 
+#
 # * Dan Brickley led the design of the RDF format.
-# 
+#
 # == License
-# 
+#
 # RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.  It
 # is free software, and may be redistributed under the terms specified
 # in the README file of the Ruby distribution.
-# 
+#
 # == Warranty
-# 
+#
 # This software is provided "as is" and without any express or implied
 # warranties, including, without limitation, the implied warranties of
 # merchantibility and fitness for a particular purpose.
@@ -254,7 +254,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 
   ##
   # Name of the dotfile that contains the description of files to be processed

data/lib/rdoc/code_objects.rb

@@ -6,8 +6,8 @@ require 'rdoc/tokenstream'
 module RDoc
 
   ##
-  # We contain the common stuff for contexts (which are containers)
-  # and other elements (methods, attributes and so on)
+  # We contain the common stuff for contexts (which are containers) and other
+  # elements (methods, attributes and so on)
 
   class CodeObject
 
@@ -31,6 +31,13 @@ module RDoc
 
     attr_reader :document_self
 
+    def initialize
+      @document_self = true
+      @document_children = true
+      @force_documentation = false
+      @done_documenting = false
+    end
+
     def document_self=(val)
       @document_self = val
       if !val
@@ -64,6 +71,14 @@ module RDoc
     # Do we _force_ documentation, even is we wouldn't normally show the entity
     attr_accessor :force_documentation
 
+    def parent_file_name
+      @parent ? @parent.file_base_name : '(unknown)'
+    end
+
+    def parent_name
+      @parent ? @parent.name : '(unknown)'
+    end
+
     # Default callbacks to nothing, but this is overridden for classes
     # and modules
     def remove_classes_and_modules
@@ -72,13 +87,6 @@ module RDoc
     def remove_methods_etc
     end
 
-    def initialize
-      @document_self = true
-      @document_children = true
-      @force_documentation = false
-      @done_documenting = false
-    end
-
     # Access the code object's comment
     attr_reader :comment
 
@@ -106,15 +114,24 @@ module RDoc
 
   end
 
-  # A Context is something that can hold modules, classes, methods, 
-  # attributes, aliases, requires, and includes. Classes, modules, and
-  # files are all Contexts.
+  ##
+  # A Context is something that can hold modules, classes, methods,
+  # attributes, aliases, requires, and includes. Classes, modules, and files
+  # are all Contexts.
 
   class Context < CodeObject
-    attr_reader   :name, :method_list, :attributes, :aliases, :constants
-    attr_reader   :requires, :includes, :in_files, :visibility
 
-    attr_reader   :sections
+    attr_reader :aliases
+    attr_reader :attributes
+    attr_reader :constants
+    attr_reader :current_section
+    attr_reader :in_files
+    attr_reader :includes
+    attr_reader :method_list
+    attr_reader :name
+    attr_reader :requires
+    attr_reader :sections
+    attr_reader :visibility
 
     class Section
       attr_reader :title, :comment, :sequence
@@ -129,12 +146,22 @@ module RDoc
         set_comment(comment)
       end
 
-      private
+      def ==(other)
+        self.class === other and @sequence == other.sequence
+      end
+
+      def inspect
+        "#<%s:0x%x %s %p>" % [
+          self.class, object_id,
+          @sequence, title
+        ]
+      end
 
-      # Set the comment for this section from the original comment block
-      # If the first line contains :section:, strip it and use the rest. Otherwise
-      # remove lines up to the line containing :section:, and look for 
-      # those lines again at the end and remove them. This lets us write
+      ##
+      # Set the comment for this section from the original comment block If
+      # the first line contains :section:, strip it and use the rest.
+      # Otherwise remove lines up to the line containing :section:, and look
+      # for those lines again at the end and remove them. This lets us write
       #
       #   # ---------------------
       #   # :SECTION: The title
@@ -144,9 +171,10 @@ module RDoc
       def set_comment(comment)
         return unless comment
 
-        if comment =~ /^.*?:section:.*$/
+        if comment =~ /^#[ \t]*:section:.*\n/
           start = $`
           rest = $'
+
           if start.empty?
             @comment = rest
           else
@@ -157,13 +185,13 @@ module RDoc
         end
         @comment = nil if @comment.empty?
       end
-    end
 
+    end
 
     def initialize
-      super()
+      super
 
-      @in_files    = []
+      @in_files = []
 
       @name    ||= "unknown"
       @comment ||= ""
@@ -177,29 +205,37 @@ module RDoc
       initialize_classes_and_modules
     end
 
+    ##
     # map the class hash to an array externally
+
     def classes
       @classes.values
     end
 
+    ##
     # map the module hash to an array externally
+
     def modules
       @modules.values
     end
 
+    ##
     # Change the default visibility for new methods
+
     def ongoing_visibility=(vis)
       @visibility = vis
     end
 
-    # Given an array +methods+ of method names, set the
-    # visibility of the corresponding AnyMethod object
+    ##
+    # Yields Method and Attr entries matching the list of names in +methods+.
+    # Attributes are only returned when +singleton+ is false.
 
-    def set_visibility_for(methods, vis, singleton=false)
+    def methods_matching(methods, singleton = false)
       count = 0
+
       @method_list.each do |m|
-        if methods.include?(m.name) && m.singleton == singleton
-          m.visibility = vis
+        if methods.include? m.name and m.singleton == singleton then
+          yield m
           count += 1
         end
       end
@@ -209,14 +245,23 @@ module RDoc
       # perhaps we need to look at attributes
 
       @attributes.each do |a|
-        if methods.include?(a.name)
-          a.visibility = vis
-          count += 1
-        end
+        yield a if methods.include? a.name
       end
     end
 
+    ##
+    # Given an array +methods+ of method names, set the visibility of the
+    # corresponding AnyMethod object
+
+    def set_visibility_for(methods, vis, singleton = false)
+      methods_matching methods, singleton do |m|
+        m.visibility = vis
+      end
+    end
+
+    ##
     # Record the file that we happen to find it in
+
     def record_location(toplevel)
       @in_files << toplevel unless @in_files.include?(toplevel)
     end
@@ -227,7 +272,7 @@ module RDoc
     end
 
     def add_class(class_type, name, superclass)
-      add_class_or_module(@classes, class_type, name, superclass)
+      add_class_or_module @classes, class_type, name, superclass
     end
 
     def add_module(class_type, name)
@@ -235,7 +280,6 @@ module RDoc
     end
 
     def add_method(a_method)
-      puts "Adding #@visibility method #{a_method.name} to #@name" if $DEBUG_RDOC
       a_method.visibility = @visibility
       add_to(@method_list, a_method)
     end
@@ -246,7 +290,8 @@ module RDoc
 
     def add_alias(an_alias)
       meth = find_instance_method_named(an_alias.old_name)
-      if meth
+
+      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
@@ -257,6 +302,8 @@ module RDoc
       else
         add_to(@aliases, an_alias)
       end
+
+      an_alias
     end
 
     def add_include(an_include)
@@ -269,20 +316,21 @@ module RDoc
 
     # Requires always get added to the top-level (file) context
     def add_require(a_require)
-      if self.kind_of? TopLevel
-        add_to(@requires, a_require)
+      if TopLevel === self then
+        add_to @requires, a_require
       else
-        parent.add_require(a_require)
+        parent.add_require a_require
       end
     end
 
     def add_class_or_module(collection, class_type, name, superclass=nil)
       cls = collection[name]
-      if cls
+
+      if cls then
+        cls.superclass = superclass unless cls.module?
         puts "Reusing class/module #{name}" if $DEBUG_RDOC
       else
         cls = class_type.new(name, superclass)
-        puts "Adding class/module #{name} to #@name" if $DEBUG_RDOC
 #        collection[name] = cls if @document_self  && !@done_documenting
         collection[name] = cls if !@done_documenting
         cls.parent = self
@@ -292,7 +340,7 @@ module RDoc
     end
 
     def add_to(array, thing)
-      array <<  thing if @document_self  && !@done_documenting
+      array << thing if @document_self and not @done_documenting
       thing.parent = self
       thing.section = @current_section
     end
@@ -371,26 +419,30 @@ module RDoc
       name <=> other.name
     end
 
-    # Look up the given symbol. If method is non-nil, then
-    # we assume the symbol references a module that
-    # contains that method
-    def find_symbol(symbol, method=nil)
+    ##
+    # Look up +symbol+.  If +method+ is non-nil, then we assume the symbol
+    # references a module that contains that method.
+
+    def find_symbol(symbol, method = nil)
       result = nil
+
       case symbol
-      when /^::(.*)/
+      when /^::(.*)/ then
         result = toplevel.find_symbol($1)
-      when /::/
+      when /::/ then
         modules = symbol.split(/::/)
-        unless modules.empty?
+
+        unless modules.empty? then
           module_name = modules.shift
           result = find_module_named(module_name)
-          if result
+          if result then
             modules.each do |name|
               result = result.find_module_named(name)
               break unless result
             end
           end
         end
+
       else
         # if a method is specified, then we're definitely looking for
         # a module, otherwise it could be any symbol
@@ -408,22 +460,21 @@ module RDoc
           end
         end
       end
-      if result && method
-        if !result.respond_to?(:find_local_symbol)
-          #p result.name
-          #p method
-          fail
-        end
+
+      if result and method then
+        fail unless result.respond_to? :find_local_symbol
         result = result.find_local_symbol(method)
       end
+
       result
     end
-           
+
     def find_local_symbol(symbol)
       res = find_method_named(symbol) ||
             find_constant_named(symbol) ||
             find_attribute_named(symbol) ||
-            find_module_named(symbol) 
+            find_module_named(symbol) ||
+            find_file_named(symbol)
     end
 
     # Handle sections
@@ -454,7 +505,14 @@ module RDoc
     def find_attribute_named(name)
       @attributes.find {|m| m.name == name}
     end
-    
+
+    ##
+    # Find a named file, or return nil
+
+    def find_file_named(name)
+      toplevel.class.find_file_named(name)
+    end
+
   end
 
   ##
@@ -465,22 +523,29 @@ module RDoc
     attr_accessor :file_relative_name
     attr_accessor :file_absolute_name
     attr_accessor :diagram
-    
+
     @@all_classes = {}
     @@all_modules = {}
+    @@all_files   = {}
 
     def self.reset
       @@all_classes = {}
       @@all_modules = {}
+      @@all_files   = {}
     end
 
     def initialize(file_name)
       super()
       @name = "TopLevel"
-      @file_relative_name = file_name
-      @file_absolute_name = file_name
-      @file_stat          = File.stat(file_name)
-      @diagram            = nil
+      @file_relative_name    = file_name
+      @file_absolute_name    = file_name
+      @file_stat             = File.stat(file_name)
+      @diagram               = nil
+      @@all_files[file_name] = self
+    end
+
+    def file_base_name
+      File.basename @file_absolute_name
     end
 
     def full_name
@@ -496,10 +561,11 @@ module RDoc
     def add_class_or_module(collection, class_type, name, superclass)
       cls = collection[name]
 
-      if cls
-        puts "Reusing class/module #{name}" if $DEBUG_RDOC
+      if cls then
+        cls.superclass = superclass unless cls.module?
+        puts "Reusing class/module #{cls.full_name}" if $DEBUG_RDOC
       else
-        if class_type == NormalModule
+        if class_type == NormalModule then
           all = @@all_modules
         else
           all = @@all_classes
@@ -507,13 +573,11 @@ module RDoc
 
         cls = all[name]
 
-        if !cls
-          cls = class_type.new(name, superclass)
+        unless cls then
+          cls = class_type.new name, superclass
           all[name] = cls unless @done_documenting
         end
 
-        puts "Adding class/module #{name} to #{@name}" if $DEBUG_RDOC
-
         collection[name] = cls unless @done_documenting
 
         cls.parent = self
@@ -534,6 +598,10 @@ module RDoc
       nil
     end
 
+    def self.find_file_named(name)
+      @@all_files[name]
+    end
+
     def find_local_symbol(symbol)
       find_class_or_module_named(symbol) || super
     end
@@ -551,14 +619,23 @@ module RDoc
       find_class_or_module_named(name) || find_enclosing_module_named(name)
     end
 
+    def inspect
+      "#<%s:0x%x %p modules: %p classes: %p>" % [
+        self.class, object_id,
+        file_base_name,
+        @modules.map { |n,m| m },
+        @classes.map { |n,c| c }
+      ]
+    end
+
   end
 
-  # ClassModule is the base class for objects representing either a
-  # class or a module.
+  ##
+  # ClassModule is the base class for objects representing either a class or a
+  # module.
 
   class ClassModule < Context
 
-    attr_reader   :superclass
     attr_accessor :diagram
 
     def initialize(name, superclass = nil)
@@ -569,7 +646,15 @@ module RDoc
       super()
     end
 
+    def find_class_named(name)
+      return self if full_name == name
+      @classes.each_value {|c| return c if c.find_class_named(name) }
+      nil
+    end
+
+    ##
     # Return the fully qualified name of this class or module
+
     def full_name
       if @parent && @parent.full_name
         @parent.full_name + "::" + @name
@@ -583,49 +668,106 @@ module RDoc
       File.join(prefix, *path) + ".html"
     end
 
-    # Return +true+ if this object represents a module
-    def is_module?
+    ##
+    # Does this object represent a module?
+
+    def module?
       false
     end
 
-    # to_s is simply for debugging
-    def to_s
-      res = self.class.name + ": " + @name 
-      res << @comment.to_s
-      res << super
-      res
+    ##
+    # Get the superclass of this class.  Attempts to retrieve the superclass'
+    # real name by following module nesting.
+
+    def superclass
+      raise NoMethodError, "#{full_name} is a module" if module?
+
+      scope = self
+
+      begin
+        superclass = scope.classes.find { |c| c.name == @superclass }
+
+        return superclass.full_name if superclass
+        scope = scope.parent
+      end until scope.nil? or TopLevel === scope
+
+      @superclass
     end
 
-    def find_class_named(name)
-      return self if full_name == name
-      @classes.each_value {|c| return c if c.find_class_named(name) }
-      nil
+    ##
+    # Set the superclass of this class
+
+    def superclass=(superclass)
+      raise NoMethodError, "#{full_name} is a module" if module?
+
+      if @superclass.nil? or @superclass == 'Object' then
+        @superclass = superclass 
+      end
+    end
+
+    def to_s
+      "#{self.class}: #{@name} #{@comment} #{super}"
     end
+
   end
 
+  ##
   # Anonymous classes
+
   class AnonClass < ClassModule
   end
 
+  ##
   # Normal classes
+
   class NormalClass < ClassModule
+
+    def inspect
+      superclass = @superclass ? " < #{@superclass}" : nil
+      "<%s:0x%x class %s%s includes: %p attributes: %p methods: %p aliases: %p>" % [
+        self.class, object_id,
+        @name, superclass, @includes, @attributes, @method_list, @aliases
+      ]
+    end
+
   end
 
+  ##
   # Singleton classes
+
   class SingleClass < ClassModule
   end
 
+  ##
   # Module
+
   class NormalModule < ClassModule
-    def is_module?
+
+    def comment=(comment)
+      return if comment.empty?
+      comment = @comment << "# ---\n" << comment unless @comment.empty?
+
+      super
+    end
+
+    def inspect
+      "#<%s:0x%x module %s includes: %p attributes: %p methods: %p aliases: %p>" % [
+        self.class, object_id,
+        @name, @includes, @attributes, @method_list, @aliases
+      ]
+    end
+
+    def module?
       true
     end
+
   end
 
   ##
   # AnyMethod is the base class for objects representing methods
 
   class AnyMethod < CodeObject
+
     attr_accessor :name
     attr_accessor :visibility
     attr_accessor :block_params
@@ -663,44 +805,71 @@ module RDoc
       @name <=> other.name
     end
 
-    def to_s
-      res = self.class.name + ": " + @name + " (" + @text + ")\n"
-      res << @comment.to_s
-      res
+    def add_alias(method)
+      @aliases << method
+    end
+
+    def inspect
+      alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
+      "#<%s:0x%x %s%s%s (%s)%s>" % [
+        self.class, object_id,
+        parent_name,
+        singleton ? '::' : '#',
+        name,
+        visibility,
+        alias_for,
+      ]
     end
 
     def param_seq
-      p = params.gsub(/\s*\#.*/, '')
-      p = p.tr("\n", " ").squeeze(" ")
-      p = "(" + p + ")" unless p[0] == ?(
+      params = params.gsub(/\s*\#.*/, '')
+      params = params.tr("\n", " ").squeeze(" ")
+      params = "(#{params})" unless p[0] == ?(
 
-      if (block = block_params)
-        # If this method has explicit block parameters, remove any
-        # explicit &block
-$stderr.puts p
-        p.sub!(/,?\s*&\w+/)
-$stderr.puts p
+      if block = block_params then # yes, =
+        # If this method has explicit block parameters, remove any explicit
+        # &block
+        params.sub!(/,?\s*&\w+/)
 
         block.gsub!(/\s*\#.*/, '')
         block = block.tr("\n", " ").squeeze(" ")
         if block[0] == ?(
           block.sub!(/^\(/, '').sub!(/\)/, '')
         end
-        p << " {|#{block}| ...}"
+        params << " { |#{block}| ... }"
       end
-      p
+
+      params
     end
 
-    def add_alias(method)
-      @aliases << method
+    def to_s
+      res = self.class.name + ": " + @name + " (" + @text + ")\n"
+      res << @comment.to_s
+      res
     end
+
+  end
+
+  ##
+  # GhostMethod represents a method referenced only by a comment
+
+  class GhostMethod < AnyMethod
+  end
+
+  ##
+  # MetaMethod represents a meta-programmed method
+
+  class MetaMethod < AnyMethod
   end
 
-  # Represent an alias, which is an old_name/ new_name pair associated
-  # with a particular context
+  ##
+  # Represent an alias, which is an old_name/ new_name pair associated with a
+  # particular context
+
   class Alias < CodeObject
+
     attr_accessor :text, :old_name, :new_name, :comment
-    
+
     def initialize(text, old_name, new_name, comment)
       super()
       @text = text
@@ -709,12 +878,22 @@ $stderr.puts p
       self.comment = comment
     end
 
+    def inspect
+      "#<%s:0x%x %s.alias_method %s, %s>" % [
+        self.class, object_id,
+        parent.name, @old_name, @new_name,
+      ]
+    end
+
     def to_s
       "alias: #{self.old_name} ->  #{self.new_name}\n#{self.comment}"
     end
+
   end
 
+  ##
   # Represent a constant
+
   class Constant < CodeObject
     attr_accessor :name, :value
 
@@ -726,7 +905,9 @@ $stderr.puts p
     end
   end
 
+  ##
   # Represent attributes
+
   class Attr < CodeObject
     attr_accessor :text, :name, :rw, :visibility
 
@@ -739,16 +920,33 @@ $stderr.puts p
       self.comment = comment
     end
 
+    def <=>(other)
+      self.name <=> other.name
+    end
+
+    def inspect
+      attr = case rw
+             when 'RW' then :attr_accessor
+             when 'R'  then :attr_reader
+             when 'W'  then :attr_writer
+             else
+               " (#{rw})"
+             end
+
+      "#<%s:0x%x %s.%s :%s>" % [
+        self.class, object_id,
+        parent_name, attr, @name,
+      ]
+    end
+
     def to_s
       "attr: #{self.name} #{self.rw}\n#{self.comment}"
     end
 
-    def <=>(other)
-      self.name <=> other.name
-    end
   end
 
-  # a required file
+  ##
+  # A required file
 
   class Require < CodeObject
     attr_accessor :name
@@ -759,16 +957,37 @@ $stderr.puts p
       self.comment = comment
     end
 
+    def inspect
+      "#<%s:0x%x require '%s' in %s>" % [
+        self.class,
+        object_id,
+        @name,
+        parent_file_name,
+      ]
+    end
+
   end
 
-  # an included module
+  ##
+  # An included module
+
   class Include < CodeObject
+
     attr_accessor :name
 
     def initialize(name, comment)
       super()
       @name = name
       self.comment = comment
+
+    end
+
+    def inspect
+      "#<%s:0x%x %s.include %s>" % [
+        self.class,
+        object_id,
+        parent_name, @name,
+      ]
     end
 
   end