rdoc 2.0.0

data/History.txt

@@ -0,0 +1,13 @@
+=== 2.0.0 / 2008-04-10
+
+* 3 Major Enhancements:
+  * Renamespaced everything RDoc under the RDoc module.
+  * New `ri` implementation.
+    * Reads from a cache in ~/.ri/ for enhanced speed.
+    * RubyGems aware, only searches latest gem versions.
+  * Now up to over 100 tests and 200 assertions.
+* 4 Minor Enhancements:
+  * Switched to an ERb-based TemplatePage, see RDoc::TemplatePage.
+  * Class/module ri now displays attribute and constant comments.
+  * Cross-references can be disabled with a leading \.
+  * Relaxed parsing for some RDoc inline markup.

data/Manifest.txt

@@ -0,0 +1,61 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/rdoc
+bin/ri
+lib/rdoc.rb
+lib/rdoc/code_objects.rb
+lib/rdoc/diagram.rb
+lib/rdoc/dot.rb
+lib/rdoc/generator.rb
+lib/rdoc/generator/chm.rb
+lib/rdoc/generator/chm/chm.rb
+lib/rdoc/generator/html.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/xml.rb
+lib/rdoc/generator/xml/rdf.rb
+lib/rdoc/generator/xml/xml.rb
+lib/rdoc/markup.rb
+lib/rdoc/markup/attribute_manager.rb
+lib/rdoc/markup/formatter.rb
+lib/rdoc/markup/fragments.rb
+lib/rdoc/markup/inline.rb
+lib/rdoc/markup/lines.rb
+lib/rdoc/markup/preprocess.rb
+lib/rdoc/markup/to_flow.rb
+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/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/rdoc.rb
+lib/rdoc/ri.rb
+lib/rdoc/ri/cache.rb
+lib/rdoc/ri/descriptions.rb
+lib/rdoc/ri/display.rb
+lib/rdoc/ri/driver.rb
+lib/rdoc/ri/formatter.rb
+lib/rdoc/ri/paths.rb
+lib/rdoc/ri/reader.rb
+lib/rdoc/ri/util.rb
+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_markup.rb
+test/test_rdoc_markup_attribute_manager.rb
+test/test_rdoc_ri_attribute_formatter.rb
+test/test_rdoc_ri_default_display.rb
+test/test_rdoc_ri_formatter.rb
+test/test_rdoc_ri_overstrike_formatter.rb

data/README.txt

@@ -0,0 +1,34 @@
+= RDoc
+
+* http://rubyforge.org/projects/rdoc/
+
+== DESCRIPTION:
+
+RDoc is an application that produces documentation for one or more Ruby source
+files.  RDoc includes the `rdoc` and `ri` tools for generating and displaying
+online documentation.
+
+At this point in time, RDoc 2.x is a work in progress and may incur further
+API changes beyond what has been made to the RDoc 1.0.1.  Command-line tools
+are largely unaffected, but internal APIs may shift rapidly.
+
+== SYNOPSIS:
+
+  gem 'rdoc'
+  require 'rdoc/rdoc'
+  # ... see RDoc
+
+== BUGS:
+
+If you found a bug, please report it at the RDoc project's tracker on
+RubyForge:
+
+http://rubyforge.org/tracker/?group_id=627
+
+== LICENSE:
+
+RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers,
+portions (c) 2007-2008 Eric Hodel.  It is free software, and may be
+redistributed under the terms specified in the README file of the Ruby
+distribution.
+

data/Rakefile

@@ -0,0 +1,10 @@
+require 'hoe'
+
+$:.unshift 'lib'
+require 'rdoc'
+
+Hoe.new "rdoc", RDoc::VERSION do |rdoc|
+  rdoc.developer 'Eric Hodel', 'drbrain@segment7.net'
+  rdoc.developer 'Dave Thomas', ''
+end
+

data/bin/rdoc

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+#
+#  RDoc: Documentation tool for source code
+#        (see lib/rdoc/rdoc.rb for more information)
+#
+#  Copyright (c) 2003 Dave Thomas
+#  Released under the same terms as Ruby
+#
+#  $Revision: 15033 $
+
+require 'rdoc/rdoc'
+
+begin
+  r = RDoc::RDoc.new
+  r.document ARGV
+rescue Interrupt
+  $stderr.puts
+  $stderr.puts "Interrupted"
+rescue RDoc::Error => e
+  $stderr.puts e.message
+  exit 1
+end

data/bin/ri

@@ -0,0 +1,6 @@
+#!/usr//bin/env ruby
+
+require 'rdoc/ri/driver'
+
+RDoc::RI::Driver.run ARGV
+

data/lib/rdoc.rb

@@ -0,0 +1,277 @@
+$DEBUG_RDOC = nil
+
+##
+# = 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,
+# modules, and methods (along with includes and requires).  We associate with
+# these optional documentation contained in the immediately preceding comment
+# block, and then render the result using a pluggable output formatter.
+# 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
+# * 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 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). 
+# 
+#   % 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.
+#   #--
+#   # FIXME: fails if the birthday falls on February 29th
+#   #++
+#   # The DOB is returned as a Time object.
+#   
+#   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. 
+# 
+# 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
+#   directly within the affected class or module will also be
+#   omitted.  By default, though, modules and classes within that
+#   class of module _will_ be documented.  This is turned off by
+#   adding the +all+ modifier.
+#   
+#     module MyModule # :nodoc:
+#       class Input
+#       end
+#     end
+#     
+#     module OtherModule # :nodoc: all
+#       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.
+# 
+# [+: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
+#   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
+#   the section is used as introductory text.  Subsequent methods, aliases,
+#   attributes, and classes will be documented in this section.  A :section:
+#   comment block may have one or more lines before the :section: directive.
+#   These will be removed, and any identical lines at the end of the block are
+#   also removed.  This allows you to add visual cues such as:
+#     
+#     # ----------------------------------------
+#     # :section: My Section
+#     # 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.
+# 
+# [+: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,
+#   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.
+
+module RDoc
+
+  ##
+  # Exception thrown by any rdoc error.
+
+  class Error < RuntimeError; end
+
+  RDocError = Error # :nodoc:
+
+  ##
+  # RDoc version you are using
+
+  VERSION = "2.0.0"
+
+  ##
+  # Name of the dotfile that contains the description of files to be processed
+  # in the current directory
+
+  DOT_DOC_FILENAME = ".document"
+
+  GENERAL_MODIFIERS = %w[nodoc].freeze
+
+  CLASS_MODIFIERS = GENERAL_MODIFIERS
+
+  ATTR_MODIFIERS  = GENERAL_MODIFIERS
+
+  CONSTANT_MODIFIERS = GENERAL_MODIFIERS
+
+  METHOD_MODIFIERS = GENERAL_MODIFIERS +
+    %w[arg args yield yields notnew not-new not_new doc]
+
+end
+

data/lib/rdoc/code_objects.rb

@@ -0,0 +1,776 @@
+# We represent the various high-level code constructs that appear
+# in Ruby programs: classes, modules, methods, and so on.
+
+require 'rdoc/tokenstream'
+
+module RDoc
+
+  ##
+  # We contain the common stuff for contexts (which are containers)
+  # and other elements (methods, attributes and so on)
+
+  class CodeObject
+
+    attr_accessor :parent
+
+    # We are the model of the code, but we know that at some point
+    # we will be worked on by viewers. By implementing the Viewable
+    # protocol, viewers can associated themselves with these objects.
+
+    attr_accessor :viewer
+
+    # are we done documenting (ie, did we come across a :enddoc:)?
+
+    attr_accessor :done_documenting
+
+    # Which section are we in
+
+    attr_accessor :section
+
+    # do we document ourselves?
+
+    attr_reader :document_self
+
+    def document_self=(val)
+      @document_self = val
+      if !val
+	remove_methods_etc
+      end
+    end
+
+    # set and cleared by :startdoc: and :enddoc:, this is used to toggle
+    # the capturing of documentation
+    def start_doc
+      @document_self = true
+      @document_children = true
+    end
+
+    def stop_doc
+      @document_self = false
+      @document_children = false
+    end
+
+    # do we document ourselves and our children
+
+    attr_reader :document_children
+
+    def document_children=(val)
+      @document_children = val
+      if !val
+	remove_classes_and_modules
+      end
+    end
+
+    # Do we _force_ documentation, even is we wouldn't normally show the entity
+    attr_accessor :force_documentation
+
+    # Default callbacks to nothing, but this is overridden for classes
+    # and modules
+    def remove_classes_and_modules
+    end
+
+    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
+
+    # Update the comment, but don't overwrite a real comment with an empty one
+    def comment=(comment)
+      @comment = comment unless comment.empty?
+    end
+
+    # There's a wee trick we pull. Comment blocks can have directives that
+    # override the stuff we extract during the parse. So, we have a special
+    # class method, attr_overridable, that lets code objects list
+    # those directives. Wehn a comment is assigned, we then extract
+    # out any matching directives and update our object
+
+    def self.attr_overridable(name, *aliases)
+      @overridables ||= {}
+
+      attr_accessor name
+
+      aliases.unshift name
+      aliases.each do |directive_name|
+        @overridables[directive_name.to_s] = name
+      end
+    end
+
+  end
+
+  # 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
+
+    class Section
+      attr_reader :title, :comment, :sequence
+
+      @@sequence = "SEC00000"
+
+      def initialize(title, comment)
+        @title = title
+        @@sequence.succ!
+        @sequence = @@sequence.dup
+        @comment = nil
+        set_comment(comment)
+      end
+
+      private
+
+      # 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
+      #   # The body
+      #   # ---------------------
+
+      def set_comment(comment)
+        return unless comment
+
+        if comment =~ /^.*?:section:.*$/
+          start = $`
+          rest = $'
+          if start.empty?
+            @comment = rest
+          else
+            @comment = rest.sub(/#{start.chomp}\Z/, '')
+          end
+        else
+          @comment = comment
+        end
+        @comment = nil if @comment.empty?
+      end
+    end
+
+
+    def initialize
+      super()
+
+      @in_files    = []
+
+      @name    ||= "unknown"
+      @comment ||= ""
+      @parent  = nil
+      @visibility = :public
+
+      @current_section = Section.new(nil, nil)
+      @sections = [ @current_section ]
+
+      initialize_methods_etc
+      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
+
+    def set_visibility_for(methods, vis, singleton=false)
+      count = 0
+      @method_list.each do |m|
+        if methods.include?(m.name) && m.singleton == singleton
+          m.visibility = vis
+          count += 1
+        end
+      end
+
+      return if count == methods.size || singleton
+
+      # perhaps we need to look at attributes
+
+      @attributes.each do |a|
+        if methods.include?(a.name)
+          a.visibility = vis
+          count += 1
+        end
+      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
+
+    # Return true if at least part of this thing was defined in +file+
+    def defined_in?(file)
+      @in_files.include?(file)
+    end
+
+    def add_class(class_type, name, superclass)
+      add_class_or_module(@classes, class_type, name, superclass)
+    end
+
+    def add_module(class_type, name)
+      add_class_or_module(@modules, class_type, name, nil)
+    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
+
+    def add_attribute(an_attribute)
+      add_to(@attributes, an_attribute)
+    end
+
+    def add_alias(an_alias)
+      meth = find_instance_method_named(an_alias.old_name)
+      if 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)
+      else
+        add_to(@aliases, an_alias)
+      end
+    end
+
+    def add_include(an_include)
+      add_to(@includes, an_include)
+    end
+
+    def add_constant(const)
+      add_to(@constants, const)
+    end
+
+    # 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)
+      else
+        parent.add_require(a_require)
+      end
+    end
+
+    def add_class_or_module(collection, class_type, name, superclass=nil)
+      cls = collection[name]
+      if cls
+        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
+        cls.section = @current_section
+      end
+      cls
+    end
+
+    def add_to(array, thing)
+      array <<  thing if @document_self  && !@done_documenting
+      thing.parent = self
+      thing.section = @current_section
+    end
+
+    # If a class's documentation is turned off after we've started
+    # collecting methods etc., we need to remove the ones
+    # we have
+
+    def remove_methods_etc
+      initialize_methods_etc
+    end
+
+    def initialize_methods_etc
+      @method_list = []
+      @attributes  = []
+      @aliases     = []
+      @requires    = []
+      @includes    = []
+      @constants   = []
+    end
+
+    # and remove classes and modules when we see a :nodoc: all
+    def remove_classes_and_modules
+      initialize_classes_and_modules
+    end
+
+    def initialize_classes_and_modules
+      @classes     = {}
+      @modules     = {}
+    end
+
+    # Find a named module
+    def find_module_named(name)
+      return self if self.name == name
+      res = @modules[name] || @classes[name]
+      return res if res
+      find_enclosing_module_named(name)
+    end
+
+    # find a module at a higher scope
+    def find_enclosing_module_named(name)
+      parent && parent.find_module_named(name)
+    end
+
+    # Iterate over all the classes and modules in
+    # this object
+
+    def each_classmodule
+      @modules.each_value {|m| yield m}
+      @classes.each_value {|c| yield c}
+    end
+
+    def each_method
+      @method_list.each {|m| yield m}
+    end
+
+    def each_attribute 
+      @attributes.each {|a| yield a}
+    end
+
+    def each_constant
+      @constants.each {|c| yield c}
+    end
+
+    # Return the toplevel that owns us
+
+    def toplevel
+      return @toplevel if defined? @toplevel
+      @toplevel = self
+      @toplevel = @toplevel.parent until TopLevel === @toplevel
+      @toplevel
+    end
+
+    # allow us to sort modules by name
+    def <=>(other)
+      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)
+      result = nil
+      case symbol
+      when /^::(.*)/
+        result = toplevel.find_symbol($1)
+      when /::/
+        modules = symbol.split(/::/)
+        unless modules.empty?
+          module_name = modules.shift
+          result = find_module_named(module_name)
+          if result
+            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
+        if method
+          result = find_module_named(symbol)
+        else
+          result = find_local_symbol(symbol)
+          if result.nil?
+            if symbol =~ /^[A-Z]/
+              result = parent
+              while result && result.name != symbol
+                result = result.parent
+              end
+            end
+          end
+        end
+      end
+      if result && method
+        if !result.respond_to?(:find_local_symbol)
+          #p result.name
+          #p method
+          fail
+        end
+        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) 
+    end
+
+    # Handle sections
+
+    def set_current_section(title, comment)
+      @current_section = Section.new(title, comment)
+      @sections << @current_section
+    end
+
+    private
+
+    # Find a named method, or return nil
+    def find_method_named(name)
+      @method_list.find {|meth| meth.name == name}
+    end
+
+    # Find a named instance method, or return nil
+    def find_instance_method_named(name)
+      @method_list.find {|meth| meth.name == name && !meth.singleton}
+    end
+
+    # Find a named constant, or return nil
+    def find_constant_named(name)
+      @constants.find {|m| m.name == name}
+    end
+
+    # Find a named attribute, or return nil
+    def find_attribute_named(name)
+      @attributes.find {|m| m.name == name}
+    end
+    
+  end
+
+  ##
+  # A TopLevel context is a source file
+
+  class TopLevel < Context
+    attr_accessor :file_stat
+    attr_accessor :file_relative_name
+    attr_accessor :file_absolute_name
+    attr_accessor :diagram
+    
+    @@all_classes = {}
+    @@all_modules = {}
+
+    def self.reset
+      @@all_classes = {}
+      @@all_modules = {}
+    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
+    end
+
+    def full_name
+      nil
+    end
+
+    ##
+    # Adding a class or module to a TopLevel is special, as we only want one
+    # copy of a particular top-level class. For example, if both file A and
+    # file B implement class C, we only want one ClassModule object for C.
+    # This code arranges to share classes and modules between files.
+
+    def add_class_or_module(collection, class_type, name, superclass)
+      cls = collection[name]
+
+      if cls
+        puts "Reusing class/module #{name}" if $DEBUG_RDOC
+      else
+        if class_type == NormalModule
+          all = @@all_modules
+        else
+          all = @@all_classes
+        end
+
+        cls = all[name]
+
+        if !cls
+          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
+      end
+
+      cls
+    end
+
+    def self.all_classes_and_modules
+      @@all_classes.values + @@all_modules.values
+    end
+
+    def self.find_class_named(name)
+     @@all_classes.each_value do |c|
+        res = c.find_class_named(name) 
+        return res if res
+      end
+      nil
+    end
+
+    def find_local_symbol(symbol)
+      find_class_or_module_named(symbol) || super
+    end
+
+    def find_class_or_module_named(symbol)
+      @@all_classes.each_value {|c| return c if c.name == symbol}
+      @@all_modules.each_value {|m| return m if m.name == symbol}
+      nil
+    end
+
+    ##
+    # Find a named module
+
+    def find_module_named(name)
+      find_class_or_module_named(name) || find_enclosing_module_named(name)
+    end
+
+  end
+
+  # 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)
+      @name       = name
+      @diagram    = nil
+      @superclass = superclass
+      @comment    = ""
+      super()
+    end
+
+    # Return the fully qualified name of this class or module
+    def full_name
+      if @parent && @parent.full_name
+        @parent.full_name + "::" + @name
+      else
+        @name
+      end
+    end
+
+    def http_url(prefix)
+      path = full_name.split("::")
+      File.join(prefix, *path) + ".html"
+    end
+
+    # Return +true+ if this object represents a module
+    def is_module?
+      false
+    end
+
+    # to_s is simply for debugging
+    def to_s
+      res = self.class.name + ": " + @name 
+      res << @comment.to_s
+      res << super
+      res
+    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
+  end
+
+  # Anonymous classes
+  class AnonClass < ClassModule
+  end
+
+  # Normal classes
+  class NormalClass < ClassModule
+  end
+
+  # Singleton classes
+  class SingleClass < ClassModule
+  end
+
+  # Module
+  class NormalModule < ClassModule
+    def is_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
+    attr_accessor :dont_rename_initialize
+    attr_accessor :singleton
+    attr_reader :text
+
+    # list of other names for this method
+    attr_reader   :aliases
+
+    # method we're aliasing
+    attr_accessor :is_alias_for
+
+    attr_overridable :params, :param, :parameters, :parameter
+
+    attr_accessor :call_seq
+
+    include TokenStream
+
+    def initialize(text, name)
+      super()
+      @text = text
+      @name = name
+      @token_stream  = nil
+      @visibility    = :public
+      @dont_rename_initialize = false
+      @block_params  = nil
+      @aliases       = []
+      @is_alias_for  = nil
+      @comment = ""
+      @call_seq = nil
+    end
+
+    def <=>(other)
+      @name <=> other.name
+    end
+
+    def to_s
+      res = self.class.name + ": " + @name + " (" + @text + ")\n"
+      res << @comment.to_s
+      res
+    end
+
+    def param_seq
+      p = params.gsub(/\s*\#.*/, '')
+      p = p.tr("\n", " ").squeeze(" ")
+      p = "(" + p + ")" 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
+
+        block.gsub!(/\s*\#.*/, '')
+        block = block.tr("\n", " ").squeeze(" ")
+        if block[0] == ?(
+          block.sub!(/^\(/, '').sub!(/\)/, '')
+        end
+        p << " {|#{block}| ...}"
+      end
+      p
+    end
+
+    def add_alias(method)
+      @aliases << method
+    end
+  end
+
+  # 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
+      @old_name = old_name
+      @new_name = new_name
+      self.comment = comment
+    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
+
+    def initialize(name, value, comment)
+      super()
+      @name = name
+      @value = value
+      self.comment = comment
+    end
+  end
+
+  # Represent attributes
+  class Attr < CodeObject
+    attr_accessor :text, :name, :rw, :visibility
+
+    def initialize(text, name, rw, comment)
+      super()
+      @text = text
+      @name = name
+      @rw = rw
+      @visibility = :public
+      self.comment = comment
+    end
+
+    def to_s
+      "attr: #{self.name} #{self.rw}\n#{self.comment}"
+    end
+
+    def <=>(other)
+      self.name <=> other.name
+    end
+  end
+
+  # a required file
+
+  class Require < CodeObject
+    attr_accessor :name
+
+    def initialize(name, comment)
+      super()
+      @name = name.gsub(/'|"/, "") #'
+      self.comment = comment
+    end
+
+  end
+
+  # an included module
+  class Include < CodeObject
+    attr_accessor :name
+
+    def initialize(name, comment)
+      super()
+      @name = name
+      self.comment = comment
+    end
+
+  end
+
+end