rdoc 2.3.0 → 2.4.0

data/lib/rdoc/attr.rb

@@ -0,0 +1,79 @@
+require 'rdoc/code_object'
+
+##
+# An attribute created by \#attr, \#attr_reader, \#attr_writer or
+# \#attr_accessor
+
+class RDoc::Attr < RDoc::CodeObject
+
+  ##
+  # Name of the attribute
+
+  attr_accessor :name
+
+  ##
+  # Is the attribute readable, writable or both?
+
+  attr_accessor :rw
+
+  ##
+  # Source file token stream
+
+  attr_accessor :text
+
+  ##
+  # public, protected, private
+
+  attr_accessor :visibility
+
+  def initialize(text, name, rw, comment)
+    super()
+    @text = text
+    @name = name
+    @rw = rw
+    @visibility = :public
+    self.comment = comment
+  end
+
+  ##
+  # Attributes are ordered by name
+
+  def <=>(other)
+    self.name <=> other.name
+  end
+
+  ##
+  # An HTML id-friendly representation of #name
+
+  def html_name
+    @name.gsub(/[^a-z]+/, '-')
+  end
+
+  def inspect # :nodoc:
+    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
+
+  ##
+  # URL path for this attribute
+
+  def path
+    "#{@parent.path}##{@name}"
+  end
+
+  def to_s # :nodoc:
+    "attr: #{self.name} #{self.rw}\n#{self.comment}"
+  end
+
+end
+

data/lib/rdoc/cache.rb

@@ -9,24 +9,33 @@ class RDoc::Cache
 
   include Singleton
 
+  ##
+  # Creates a new, empty cache
+
   def initialize
     @contents = {}
     @lock = Mutex.new
   end
 
+  ##
   # Checks whether there's a value in the cache with key +key+. If so, then
-  # that value will be returned. Otherwise, the given block will be run,
-  # and its return value will be put into the cache, and returned.
+  # that value will be returned. Otherwise, the given block will be run, and
+  # its return value will be put into the cache, and returned.
+
   def cache(key)
     @lock.synchronize do
       @contents[key] ||= yield
     end
   end
 
+  ##
+  # Clears the contents of the cache
+
   def clear
     @lock.synchronize do
       @contents.clear
     end
   end
+
 end
 

data/lib/rdoc/class_module.rb

@@ -0,0 +1,87 @@
+require 'rdoc/context'
+
+##
+# ClassModule is the base class for objects representing either a class or a
+# module.
+
+class RDoc::ClassModule < RDoc::Context
+
+  attr_accessor :diagram
+
+  ##
+  # Creates a new ClassModule with +name+ with optional +superclass+
+
+  def initialize(name, superclass = 'Object')
+    @diagram    = nil
+    @full_name  = nil
+    @name       = name
+    @superclass = superclass
+    super()
+  end
+
+  ##
+  # Finds a class or module with +name+ in this namespace or its descendents
+
+  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
+    @full_name ||= if RDoc::ClassModule === @parent then
+                     "#{@parent.full_name}::#{@name}"
+                   else
+                     @name
+                   end
+  end
+
+  ##
+  # 'module' or 'class'
+
+  def type
+    module? ? 'module' : 'class'
+  end
+
+  ##
+  # Does this object represent a module?
+
+  def module?
+    false
+  end
+
+  ##
+  # Path to this class or module
+
+  def path
+    http_url RDoc::RDoc.current.generator.class_dir
+  end
+
+  ##
+  # Get the superclass of this class.  Attempts to retrieve the superclass
+  # object, returns the name if it is not known.
+
+  def superclass
+    raise NoMethodError, "#{full_name} is a module" if module?
+
+    RDoc::TopLevel.find_class_named(@superclass) || @superclass
+  end
+
+  ##
+  # Set the superclass of this class to +superclass+
+
+  def superclass=(superclass)
+    raise NoMethodError, "#{full_name} is a module" if module?
+
+    @superclass = superclass if @superclass.nil? or @superclass == 'Object'
+  end
+
+  def to_s # :nodoc:
+    "#{self.class}: #{full_name} #{@comment} #{super}"
+  end
+
+end
+

data/lib/rdoc/code_object.rb

@@ -0,0 +1,152 @@
+require 'rdoc'
+
+##
+# We contain the common stuff for contexts (which are containers) and other
+# elements (methods, attributes and so on)
+
+class RDoc::CodeObject
+
+  ##
+  # Our comment
+
+  attr_reader :comment
+
+  ##
+  # Do we document our children?
+
+  attr_reader :document_children
+
+  ##
+  # Do we document ourselves?
+
+  attr_reader :document_self
+
+  ##
+  # Are we done documenting (ie, did we come across a :enddoc:)?
+
+  attr_accessor :done_documenting
+
+  ##
+  # Force documentation of this CodeObject
+
+  attr_accessor :force_documentation
+
+  ##
+  # Our parent CodeObject
+
+  attr_accessor :parent
+
+  ##
+  # Which section are we in
+
+  attr_accessor :section
+
+  ##
+  # 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
+
+  ##
+  # 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. When 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
+
+  ##
+  # Creates a new CodeObject that will document itself and its children
+
+  def initialize
+    @comment = nil
+    @document_children = true
+    @document_self = true
+    @done_documenting = false
+    @force_documentation = false
+    @parent = nil
+  end
+
+  ##
+  # Replaces our comment with +comment+, unless it is empty.
+
+  def comment=(comment)
+    @comment = comment unless comment.empty?
+  end
+
+  ##
+  # Enables or disables documentation of this CodeObject's children.  Calls
+  # remove_classes_and_modules when disabling.
+
+  def document_children=(document_children)
+    @document_children = document_children
+    remove_classes_and_modules unless document_children
+  end
+
+  ##
+  # Enables or disables documentation of this CodeObject.  Calls
+  # remove_methods_etc when disabling.
+
+  def document_self=(document_self)
+    @document_self = document_self
+    remove_methods_etc unless document_self
+  end
+
+  ##
+  # File name of our parent
+
+  def parent_file_name
+    @parent ? @parent.base_name : '(unknown)'
+  end
+
+  ##
+  # Name of our parent
+
+  def parent_name
+    @parent ? @parent.full_name : '(unknown)'
+  end
+
+  ##
+  # Callback called upon disabling documentation of children.  See
+  # #document_children=
+
+  def remove_classes_and_modules
+  end
+
+  ##
+  # Callback called upon disabling documentation of ourself.  See
+  # #document_self=
+
+  def remove_methods_etc
+  end
+
+  ##
+  # Enable capture of documentation
+
+  def start_doc
+    @document_self = true
+    @document_children = true
+  end
+
+  ##
+  # Disable capture of documentation
+
+  def stop_doc
+    @document_self = false
+    @document_children = false
+  end
+
+end
+

data/lib/rdoc/code_objects.rb

@@ -1,1123 +1,23 @@
-# We represent the various high-level code constructs that appear
-# in Ruby programs: classes, modules, methods, and so on.
+# We represent the various high-level code constructs that appear in Ruby
+# programs: classes, modules, methods, and so on.
 
-require 'thread'
+require 'rdoc/code_object'
+require 'rdoc/context'
+require 'rdoc/top_level'
 
-require 'rdoc/tokenstream'
+require 'rdoc/class_module'
+require 'rdoc/normal_class'
+require 'rdoc/normal_module'
+require 'rdoc/anon_class'
+require 'rdoc/single_class'
 
-module RDoc
+require 'rdoc/any_method'
+require 'rdoc/alias'
+require 'rdoc/ghost_method'
+require 'rdoc/meta_method'
 
-  ##
-  # We contain the common stuff for contexts (which are containers) and other
-  # elements (methods, attributes and so on)
+require 'rdoc/attr'
+require 'rdoc/constant'
+require 'rdoc/require'
+require 'rdoc/include'
 
-  class CodeObject
-
-    ##
-    # Our comment
-
-    attr_reader :comment
-
-    ##
-    # Do we document our children?
-
-    attr_reader :document_children
-
-    ##
-    # Do we document ourselves?
-
-    attr_reader :document_self
-
-    ##
-    # Are we done documenting (ie, did we come across a :enddoc:)?
-
-    attr_accessor :done_documenting
-
-    ##
-    # Our parent CodeObject
-
-    attr_accessor :parent
-
-    ##
-    # Which section are we in
-
-    attr_accessor :section
-
-    ##
-    # 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
-
-    def initialize
-      @document_self = true
-      @document_children = true
-      @force_documentation = false
-      @done_documenting = false
-    end
-
-    ##
-    # Enables or disables documentation of this CodeObject.  Calls
-    # remove_methods_etc when disabling.
-
-    def document_self=(document_self)
-      @document_self = document_self
-      remove_methods_etc unless document_self
-    end
-
-    ##
-    # Enable capture of documentation
-
-    def start_doc
-      @document_self = true
-      @document_children = true
-    end
-
-    ##
-    # Disable capture of documentation
-
-    def stop_doc
-      @document_self = false
-      @document_children = false
-    end
-
-    ##
-    # Enables or disables documentation of this CodeObject's children.  Calls
-    # remove_classes_and_modules when disabling.
-
-    def document_children=(document_children)
-      @document_children = document_children
-      remove_classes_and_modules unless document_children
-    end
-
-    ##
-    # Force documentation of this CodeObject
-
-    attr_accessor :force_documentation
-
-    ##
-    # File name of our parent
-
-    def parent_file_name
-      @parent ? @parent.file_base_name : '(unknown)'
-    end
-
-    ##
-    # Name of our parent
-
-    def parent_name
-      @parent ? @parent.name : '(unknown)'
-    end
-
-    ##
-    # Callback called upon disabling documentation of children.  See
-    # #document_children=
-
-    def remove_classes_and_modules
-    end
-
-    ##
-    # Callback called upon disabling documentation of ourself.  See
-    # #document_self=
-
-    def remove_methods_etc
-    end
-
-    ##
-    # Replaces our comment with +comment+, unless it is empty.
-
-    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. When 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 :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
-
-      @@sequence = "SEC00000"
-      @@sequence_lock = Mutex.new
-
-      def initialize(title, comment)
-        @title = title
-        @@sequence_lock.synchronize do
-          @@sequence.succ!
-          @sequence = @@sequence.dup
-        end
-        @comment = nil
-        set_comment(comment)
-      end
-
-      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
-      #
-      #   # ---------------------
-      #   # :SECTION: The title
-      #   # The body
-      #   # ---------------------
-
-      def set_comment(comment)
-        return unless comment
-
-        if comment =~ /^#[ \t]*:section:.*\n/
-          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
-
-    ##
-    # return the classes Hash (only to be used internally)
-
-    def classes_hash
-      @classes
-    end
-    protected :classes_hash
-
-    ##
-    # return the modules Hash (only to be used internally)
-
-    def modules_hash
-      @modules
-    end
-    protected :modules_hash
-
-    ##
-    # Change the default visibility for new methods
-
-    def ongoing_visibility=(vis)
-      @visibility = vis
-    end
-
-    ##
-    # Yields Method and Attr entries matching the list of names in +methods+.
-    # Attributes are only returned when +singleton+ is false.
-
-    def methods_matching(methods, singleton = false)
-      count = 0
-
-      @method_list.each do |m|
-        if methods.include? m.name and m.singleton == singleton then
-          yield m
-          count += 1
-        end
-      end
-
-      return if count == methods.size || singleton
-
-      # perhaps we need to look at attributes
-
-      @attributes.each do |a|
-        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
-
-    # 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)
-      klass = add_class_or_module @classes, class_type, name, superclass
-
-      #
-      # If the parser encounters Container::Item before encountering
-      # Container, then it assumes that Container is a module.  This
-      # may not be the case, so remove Container from the module list
-      # if present and transfer any contained classes and modules to
-      # the new class.
-      #
-      mod = @modules.delete(name)
-
-      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
-    end
-
-    def add_module(class_type, name)
-      add_class_or_module(@modules, class_type, name, nil)
-    end
-
-    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
-        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
-    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 TopLevel === self then
-        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 then
-        cls.superclass = superclass unless cls.module?
-        puts "Reusing class/module #{name}" if $DEBUG_RDOC
-      else
-        cls = class_type.new(name, superclass)
-#        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 and not @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   = []
-
-      # 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
-    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)
-      # First check the enclosed modules, then check the module itself,
-      # then check the enclosing modules (this mirrors the check done by
-      # the Ruby parser)
-      res = @modules[name] || @classes[name]
-      return res if res
-      return self if self.name == name
-      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 +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 /^::(.*)/ then
-        result = toplevel.find_symbol($1)
-      when /::/ then
-        modules = symbol.split(/::/)
-
-        unless modules.empty? then
-          module_name = modules.shift
-          result = find_module_named(module_name)
-
-          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
-        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 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_file_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
-
-    ##
-    # Find a named file, or return nil
-
-    def find_file_named(name)
-      toplevel.class.find_file_named(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
-    attr_accessor :parser
-
-    @@lock = Mutex.new
-    @@all_classes = {}
-    @@all_modules = {}
-    @@all_files   = {}
-
-    def self.reset
-      @@lock.synchronize do
-        @@all_classes = {}
-        @@all_modules = {}
-        @@all_files   = {}
-      end
-    end
-
-    def initialize(file_name)
-      super()
-      @name = "TopLevel"
-      @file_relative_name = file_name
-      @file_absolute_name = file_name
-      @file_stat          = File.stat(file_name) rescue nil # HACK for testing
-      @diagram            = nil
-      @parser             = nil
-
-      @@lock.synchronize do
-        @@all_files[file_name] = self
-      end
-    end
-
-    def file_base_name
-      File.basename @file_absolute_name
-    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 then
-        cls.superclass = superclass unless cls.module?
-        puts "Reusing class/module #{cls.full_name}" if $DEBUG_RDOC
-      else
-        all = nil
-        
-        @@lock.synchronize do
-          if class_type == NormalModule then
-            all = @@all_modules
-          else
-            all = @@all_classes
-          end
-
-          cls = all[name]
-        end
-
-        if !cls then
-          cls = class_type.new name, superclass
-          unless @done_documenting
-            @@lock.synchronize do
-              all[name] = cls
-            end
-          end
-        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
-
-        cls.parent = self
-      end
-
-      cls
-    end
-
-    def self.all_classes_and_modules
-      @@lock.synchronize do
-        @@all_classes.values + @@all_modules.values
-      end
-    end
-
-    def self.find_class_named(name)
-      @@lock.synchronize do
-        @@all_classes.each_value do |c|
-          res = c.find_class_named(name)
-          return res if res
-        end
-      end
-      nil
-    end
-
-    def self.find_file_named(name)
-      @@lock.synchronize do
-        @@all_files[name]
-      end
-    end
-
-    def find_local_symbol(symbol)
-      find_class_or_module_named(symbol) || super
-    end
-
-    def find_class_or_module_named(symbol)
-      @@lock.synchronize do
-        @@all_classes.each_value {|c| return c if c.name == symbol}
-        @@all_modules.each_value {|m| return m if m.name == symbol}
-      end
-      nil
-    end
-
-    ##
-    # Find a named module
-
-    def find_module_named(name)
-      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.
-
-  class ClassModule < Context
-
-    attr_accessor :diagram
-
-    def initialize(name, superclass = nil)
-      @name       = name
-      @diagram    = nil
-      @superclass = superclass
-      @comment    = ""
-      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
-      else
-        @name
-      end
-    end
-
-    def http_url(prefix)
-      path = full_name.split("::")
-      File.join(prefix, *path) + ".html"
-    end
-
-    ##
-    # Does this object represent a module?
-
-    def module?
-      false
-    end
-
-    ##
-    # 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
-
-    ##
-    # Set the superclass of this class
-
-    def superclass=(superclass)
-      raise NoMethodError, "#{full_name} is a module" if module?
-
-      @superclass = superclass if @superclass.nil? or @superclass == 'Object'
-    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 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
-    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 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
-      params = params.gsub(/\s*\#.*/, '')
-      params = params.tr("\n", " ").squeeze(" ")
-      params = "(#{params})" unless p[0] == ?(
-
-      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
-        params << " { |#{block}| ... }"
-      end
-
-      params
-    end
-
-    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
-
-  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 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
-
-    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 <=>(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
-
-  end
-
-  ##
-  # A required file
-
-  class Require < CodeObject
-    attr_accessor :name
-
-    def initialize(name, comment)
-      super()
-      @name = name.gsub(/'|"/, "") #'
-      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
-
-  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
-
-end