rdoc 3.1 → 6.3.3

data/lib/rdoc/context.rb

@@ -1,4 +1,5 @@
-require 'rdoc/code_object'
+# frozen_string_literal: true
+require 'cgi'
 
 ##
 # A Context is something that can hold modules, classes, methods, attributes,
@@ -14,6 +15,12 @@ class RDoc::Context < RDoc::CodeObject
 
   TYPES = %w[class instance]
 
+  ##
+  # If a context has these titles it will be sorted in this order.
+
+  TOMDOC_TITLES = [nil, 'Public', 'Internal', 'Deprecated'] # :nodoc:
+  TOMDOC_TITLES_SORT = TOMDOC_TITLES.sort_by { |title| title.to_s } # :nodoc:
+
   ##
   # Class/module aliases
 
@@ -24,15 +31,20 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_reader :attributes
 
+  ##
+  # Block params to be used in the next MethodAttr parsed under this context
+
+  attr_accessor :block_params
+
   ##
   # Constants defined
 
   attr_reader :constants
 
   ##
-  # Current section of documentation
+  # Sets the current documentation section of documentation
 
-  attr_accessor :current_section
+  attr_writer :current_section
 
   ##
   # Files this context is found in
@@ -44,6 +56,11 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_reader :includes
 
+  ##
+  # Modules this context is extended with
+
+  attr_reader :extends
+
   ##
   # Methods defined in this context
 
@@ -60,9 +77,9 @@ class RDoc::Context < RDoc::CodeObject
   attr_reader :requires
 
   ##
-  # Sections in this context
+  # Use this section for the next method, attribute or constant added.
 
-  attr_reader :sections
+  attr_accessor :temporary_section
 
   ##
   # Hash <tt>old_name => [aliases]</tt>, for aliases
@@ -72,7 +89,7 @@ class RDoc::Context < RDoc::CodeObject
   attr_accessor :unmatched_alias_lists
 
   ##
-  # Aliases that could not eventually be resolved.
+  # Aliases that could not be resolved.
 
   attr_reader :external_aliases
 
@@ -81,6 +98,11 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_accessor :visibility
 
+  ##
+  # Current visibility of this line
+
+  attr_writer :current_line_visibility
+
   ##
   # Hash of registered methods. Attributes are also registered here,
   # twice if they are RW.
@@ -88,96 +110,14 @@ class RDoc::Context < RDoc::CodeObject
   attr_reader :methods_hash
 
   ##
-  # Hash of registered constants.
+  # Params to be used in the next MethodAttr parsed under this context
 
-  attr_reader :constants_hash
+  attr_accessor :params
 
   ##
-  # A per-comment section of documentation like:
-  #
-  #   # :section: The title
-  #   # The body
-
-  class Section
-
-    ##
-    # Section comment
-
-    attr_reader :comment
-
-    ##
-    # Context this Section lives in
-
-    attr_reader :parent
-
-    ##
-    # Section sequence number (for linking)
-
-    attr_reader :sequence
-
-    ##
-    # Section title
-
-    attr_reader :title
-
-    @@sequence = "SEC00000"
-
-    ##
-    # Creates a new section with +title+ and +comment+
-
-    def initialize(parent, title, comment)
-      @parent = parent
-      @title = title
-
-      @@sequence.succ!
-      @sequence = @@sequence.dup
-
-      set_comment comment
-    end
-
-    ##
-    # Sections are equal when they have the same #sequence
-
-    def ==(other)
-      self.class === other and @sequence == other.sequence
-    end
-
-    def inspect # :nodoc:
-      "#<%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/ then
-        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
+  # Hash of registered constants.
 
-  end
+  attr_reader :constants_hash
 
   ##
   # Creates an unnamed empty context with public current visibility
@@ -188,12 +128,12 @@ class RDoc::Context < RDoc::CodeObject
     @in_files = []
 
     @name    ||= "unknown"
-    @comment ||= ""
     @parent  = nil
     @visibility = :public
 
     @current_section = Section.new self, nil, nil
-    @sections = [@current_section]
+    @sections = { nil => @current_section }
+    @temporary_section = nil
 
     @classes = {}
     @modules = {}
@@ -210,24 +150,50 @@ class RDoc::Context < RDoc::CodeObject
     @aliases     = []
     @requires    = []
     @includes    = []
+    @extends     = []
     @constants   = []
     @external_aliases = []
+    @current_line_visibility = nil
 
     # This Hash maps a method name to a list of unmatched aliases (aliases of
     # a method not yet encountered).
     @unmatched_alias_lists = {}
 
-    @methods_hash = {}
+    @methods_hash   = {}
     @constants_hash = {}
+
+    @params = nil
+
+    @store ||= nil
   end
 
   ##
   # Contexts are sorted by full_name
 
   def <=>(other)
+    return nil unless RDoc::CodeObject === other
+
     full_name <=> other.full_name
   end
 
+  ##
+  # Adds an item of type +klass+ with the given +name+ and +comment+ to the
+  # context.
+  #
+  # Currently only RDoc::Extend and RDoc::Include are supported.
+
+  def add klass, name, comment
+    if RDoc::Extend == klass then
+      ext = RDoc::Extend.new name, comment
+      add_extend ext
+    elsif RDoc::Include == klass then
+      incl = RDoc::Include.new name, comment
+      add_include incl
+    else
+      raise NotImplementedError, "adding a #{klass} is not implemented"
+    end
+  end
+
   ##
   # Adds +an_alias+ that is automatically resolved
 
@@ -265,22 +231,32 @@ class RDoc::Context < RDoc::CodeObject
     # TODO find a policy for 'attr_reader :foo' + 'def foo=()'
     register = false
 
-    if attribute.rw.index('R') then
+    key = nil
+
+    if attribute.rw.index 'R' then
       key = attribute.pretty_name
       known = @methods_hash[key]
+
       if known then
         known.comment = attribute.comment if known.comment.empty?
+      elsif registered = @methods_hash[attribute.pretty_name + '='] and
+            RDoc::Attr === registered then
+        registered.rw = 'RW'
       else
         @methods_hash[key] = attribute
         register = true
       end
     end
 
-    if attribute.rw.index('W')
-      key = attribute.pretty_name << '='
+    if attribute.rw.index 'W' then
+      key = attribute.pretty_name + '='
       known = @methods_hash[key]
+
       if known then
         known.comment = attribute.comment if known.comment.empty?
+      elsif registered = @methods_hash[attribute.pretty_name] and
+            RDoc::Attr === registered then
+        registered.rw = 'RW'
       else
         @methods_hash[key] = attribute
         register = true
@@ -292,6 +268,8 @@ class RDoc::Context < RDoc::CodeObject
       add_to @attributes, attribute
       resolve_aliases attribute
     end
+
+    attribute
   end
 
   ##
@@ -329,12 +307,12 @@ class RDoc::Context < RDoc::CodeObject
       if full_name =~ /^(.+)::(\w+)$/ then
         name = $2
         ename = $1
-        enclosing = RDoc::TopLevel.classes_hash[ename] ||
-                    RDoc::TopLevel.modules_hash[ename]
+        enclosing = @store.classes_hash[ename] || @store.modules_hash[ename]
         # HACK: crashes in actionpack/lib/action_view/helpers/form_helper.rb (metaprogramming)
         unless enclosing then
           # try the given name at top level (will work for the above example)
-          enclosing = RDoc::TopLevel.classes_hash[given_name] || RDoc::TopLevel.modules_hash[given_name]
+          enclosing = @store.classes_hash[given_name] ||
+                      @store.modules_hash[given_name]
           return enclosing if enclosing
           # not found: create the parent(s)
           names = ename.split('::')
@@ -351,6 +329,13 @@ class RDoc::Context < RDoc::CodeObject
       end
     end
 
+    # fix up superclass
+    if full_name == 'BasicObject' then
+      superclass = nil
+    elsif full_name == 'Object' then
+      superclass = '::BasicObject'
+    end
+
     # find the superclass full name
     if superclass then
       if superclass =~ /^:+/ then
@@ -367,7 +352,7 @@ class RDoc::Context < RDoc::CodeObject
       end
 
       # did we believe it was a module?
-      mod = RDoc::TopLevel.modules_hash.delete superclass
+      mod = @store.modules_hash.delete superclass
 
       upgrade_to_class mod, RDoc::NormalClass, mod.parent if mod
 
@@ -375,11 +360,12 @@ class RDoc::Context < RDoc::CodeObject
       superclass = nil if superclass == full_name
     end
 
-    klass = RDoc::TopLevel.classes_hash[full_name]
+    klass = @store.classes_hash[full_name]
 
     if klass then
       # if TopLevel, it may not be registered in the classes:
       enclosing.classes_hash[name] = klass
+
       # update the superclass if needed
       if superclass then
         existing = klass.superclass
@@ -391,7 +377,7 @@ class RDoc::Context < RDoc::CodeObject
       end
     else
       # this is a new class
-      mod = RDoc::TopLevel.modules_hash.delete full_name
+      mod = @store.modules_hash.delete full_name
 
       if mod then
         klass = upgrade_to_class mod, RDoc::NormalClass, enclosing
@@ -401,10 +387,12 @@ class RDoc::Context < RDoc::CodeObject
         klass = class_type.new name, superclass
 
         enclosing.add_class_or_module(klass, enclosing.classes_hash,
-                                      RDoc::TopLevel.classes_hash)
+                                      @store.classes_hash)
       end
     end
 
+    klass.parent = self
+
     klass
   end
 
@@ -416,15 +404,21 @@ class RDoc::Context < RDoc::CodeObject
   # to +self+, and its #section to #current_section. Returns +mod+.
 
   def add_class_or_module mod, self_hash, all_hash
-    mod.section = @current_section # TODO declaring context? something is
-                                   # wrong here...
+    mod.section = current_section # TODO declaring context? something is
+                                  # wrong here...
     mod.parent = self
+    mod.full_name = nil
+    mod.store = @store
 
     unless @done_documenting then
       self_hash[mod.name] = mod
       # this must be done AFTER adding mod to its parent, so that the full
       # name is correct:
       all_hash[mod.full_name] = mod
+      if @store.unmatched_constant_alias[mod.full_name] then
+        to, file = @store.unmatched_constant_alias[mod.full_name]
+        add_module_alias mod, mod.name, to, file
+      end
     end
 
     mod
@@ -434,50 +428,77 @@ class RDoc::Context < RDoc::CodeObject
   # Adds +constant+ if not already there. If it is, updates the comment,
   # value and/or is_alias_for of the known constant if they were empty/nil.
 
-  def add_constant(constant)
+  def add_constant constant
     return constant unless @document_self
 
     # HACK: avoid duplicate 'PI' & 'E' in math.c (1.8.7 source code)
     # (this is a #ifdef: should be handled by the C parser)
     known = @constants_hash[constant.name]
-    if known
-      #$stderr.puts "\nconstant #{constant.name} already registered"
+
+    if known then
       known.comment = constant.comment if known.comment.empty?
-      known.value = constant.value if known.value.nil? or known.value.strip.empty?
+
+      known.value = constant.value if
+        known.value.nil? or known.value.strip.empty?
+
       known.is_alias_for ||= constant.is_alias_for
     else
       @constants_hash[constant.name] = constant
       add_to @constants, constant
     end
+
+    constant
   end
 
   ##
   # Adds included module +include+ which should be an RDoc::Include
 
-  def add_include(include)
+  def add_include include
     add_to @includes, include
+
+    include
+  end
+
+  ##
+  # Adds extension module +ext+ which should be an RDoc::Extend
+
+  def add_extend ext
+    add_to @extends, ext
+
+    ext
   end
 
   ##
   # Adds +method+ if not already there. If it is (as method or attribute),
   # updates the comment if it was empty.
 
-  def add_method(method)
+  def add_method method
     return method unless @document_self
 
     # HACK: avoid duplicate 'new' in io.c & struct.c (1.8.7 source code)
     key = method.pretty_name
     known = @methods_hash[key]
-    if known
-      # TODO issue stderr messages if --verbose
-      #$stderr.puts "\n#{display(method)} already registered as #{display(known)}"
-      known.comment = method.comment if known.comment.empty?
+
+    if known then
+      if @store then # otherwise we are loading
+        known.comment = method.comment if known.comment.empty?
+        previously = ", previously in #{known.file}" unless
+          method.file == known.file
+        @store.rdoc.options.warn \
+          "Duplicate method #{known.full_name} in #{method.file}#{previously}"
+      end
     else
       @methods_hash[key] = method
-      method.visibility = @visibility
+      if @current_line_visibility
+        method.visibility, @current_line_visibility = @current_line_visibility, nil
+      else
+        method.visibility = @visibility
+      end
       add_to @method_list, method
       resolve_aliases method
     end
+
+    method
   end
 
   ##
@@ -489,41 +510,58 @@ class RDoc::Context < RDoc::CodeObject
     return mod if mod
 
     full_name = child_name name
-    mod = RDoc::TopLevel.modules_hash[full_name] || class_type.new(name)
+    mod = @store.modules_hash[full_name] || class_type.new(name)
 
-    add_class_or_module(mod, @modules, RDoc::TopLevel.modules_hash)
+    add_class_or_module mod, @modules, @store.modules_hash
   end
 
   ##
-  # Adds an alias from +from+ (a class or module) to +name+.
+  # Adds a module by +RDoc::NormalModule+ instance. See also #add_module.
 
-  def add_module_alias from, name
+  def add_module_by_normal_module(mod)
+    add_class_or_module mod, @modules, @store.modules_hash
+  end
+
+  ##
+  # Adds an alias from +from+ (a class or module) to +name+ which was defined
+  # in +file+.
+
+  def add_module_alias from, from_name, to, file
     return from if @done_documenting
 
-    to_name = child_name(name)
+    to_full_name = child_name to.name
 
     # if we already know this name, don't register an alias:
     # see the metaprogramming in lib/active_support/basic_object.rb,
-    # where we already know BasicObject as a class when we find
+    # where we already know BasicObject is a class when we find
     # BasicObject = BlankSlate
-    return from if RDoc::TopLevel.find_class_or_module(to_name)
+    return from if @store.find_class_or_module to_full_name
+
+    unless from
+      @store.unmatched_constant_alias[child_name(from_name)] = [to, file]
+      return to
+    end
 
-    if from.module? then
-      RDoc::TopLevel.modules_hash[to_name] = from
-      @modules[name] = from
+    new_to = from.dup
+    new_to.name = to.name
+    new_to.full_name = nil
+
+    if new_to.module? then
+      @store.modules_hash[to_full_name] = new_to
+      @modules[to.name] = new_to
     else
-      RDoc::TopLevel.classes_hash[to_name] = from
-      @classes[name] = from
+      @store.classes_hash[to_full_name] = new_to
+      @classes[to.name] = new_to
     end
 
-    # HACK: register a constant for this alias:
-    # constant value and comment will be updated after,
-    # when the Ruby parser adds the constant
-    const = RDoc::Constant.new(name, nil, '')
+    # Registers a constant for this alias.  The constant value and comment
+    # will be updated later, when the Ruby parser adds the constant
+    const = RDoc::Constant.new to.name, nil, new_to.comment
+    const.record_location file
     const.is_alias_for = from
     add_constant const
 
-    from
+    new_to
   end
 
   ##
@@ -539,20 +577,43 @@ class RDoc::Context < RDoc::CodeObject
     end
   end
 
+  ##
+  # Returns a section with +title+, creating it if it doesn't already exist.
+  # +comment+ will be appended to the section's comment.
+  #
+  # A section with a +title+ of +nil+ will return the default section.
+  #
+  # See also RDoc::Context::Section
+
+  def add_section title, comment = nil
+    if section = @sections[title] then
+      section.add_comment comment if comment
+    else
+      section = Section.new self, title, comment
+      @sections[title] = section
+    end
+
+    section
+  end
+
   ##
   # Adds +thing+ to the collection +array+
 
-  def add_to(array, thing)
+  def add_to array, thing
     array << thing if @document_self
-    thing.parent = self
-    thing.section = @current_section
+
+    thing.parent  = self
+    thing.store   = @store if @store
+    thing.section = current_section
   end
 
   ##
   # Is there any content?
-  # This means any of: comment, aliases, methods, attributes,
-  # external aliases, require, constant.
-  # Includes are also checked unless <tt>includes == false</tt>.
+  #
+  # This means any of: comment, aliases, methods, attributes, external
+  # aliases, require, constant.
+  #
+  # Includes and extends are also checked unless <tt>includes == false</tt>.
 
   def any_content(includes = true)
     @any_content ||= !(
@@ -564,7 +625,7 @@ class RDoc::Context < RDoc::CodeObject
       @requires.empty? &&
       @constants.empty?
     )
-    @any_content || (includes && !@includes.empty?)
+    @any_content || (includes && !(@includes + @extends).empty? )
   end
 
   ##
@@ -615,6 +676,20 @@ class RDoc::Context < RDoc::CodeObject
     @classes
   end
 
+  ##
+  # The current documentation section that new items will be added to.  If
+  # temporary_section is available it will be used.
+
+  def current_section
+    if section = @temporary_section then
+      @temporary_section = nil
+    else
+      section = @current_section
+    end
+
+    section
+  end
+
   ##
   # Is part of this thing was defined in +file+?
 
@@ -630,6 +705,16 @@ class RDoc::Context < RDoc::CodeObject
     end
   end
 
+  ##
+  # Iterator for ancestors for duck-typing.  Does nothing.  See
+  # RDoc::ClassModule#each_ancestor.
+  #
+  # This method exists to make it easy to work with Context subclasses that
+  # aren't part of RDoc.
+
+  def each_ancestor # :nodoc:
+  end
+
   ##
   # Iterator for attributes
 
@@ -658,11 +743,44 @@ class RDoc::Context < RDoc::CodeObject
     @includes.each do |i| yield i end
   end
 
+  ##
+  # Iterator for extension modules
+
+  def each_extend # :yields: extend
+    @extends.each do |e| yield e end
+  end
+
   ##
   # Iterator for methods
 
   def each_method # :yields: method
-    @method_list.sort.each {|m| yield m}
+    return enum_for __method__ unless block_given?
+
+    @method_list.sort.each { |m| yield m }
+  end
+
+  ##
+  # Iterator for each section's contents sorted by title.  The +section+, the
+  # section's +constants+ and the sections +attributes+ are yielded.  The
+  # +constants+ and +attributes+ collections are sorted.
+  #
+  # To retrieve methods in a section use #methods_by_type with the optional
+  # +section+ parameter.
+  #
+  # NOTE: Do not edit collections yielded by this method
+
+  def each_section # :yields: section, constants, attributes
+    return enum_for __method__ unless block_given?
+
+    constants  = @constants.group_by  do |constant|  constant.section end
+    attributes = @attributes.group_by do |attribute| attribute.section end
+
+    constants.default  = []
+    attributes.default = []
+
+    sort_sections.each do |section|
+      yield section, constants[section].select(&:display?).sort, attributes[section].select(&:display?).sort
+    end
   end
 
   ##
@@ -698,7 +816,9 @@ class RDoc::Context < RDoc::CodeObject
   # Finds a constant with +name+ in this context
 
   def find_constant_named(name)
-    @constants.find {|m| m.name == name}
+    @constants.find do |m|
+      m.name == name || m.full_name == name
+    end
   end
 
   ##
@@ -732,8 +852,8 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Finds a file with +name+ in this context
 
-  def find_file_named(name)
-    top_level.class.find_file_named(name)
+  def find_file_named name
+    @store.find_file_named name
   end
 
   ##
@@ -760,7 +880,13 @@ class RDoc::Context < RDoc::CodeObject
   # Finds a method named +name+ with singleton value +singleton+.
 
   def find_method(name, singleton)
-    @method_list.find { |m| m.name == name && m.singleton == singleton }
+    @method_list.find { |m|
+      if m.singleton
+        m.name == name && m.singleton == singleton
+      else
+        m.name == name && !m.singleton && !singleton
+      end
+    }
   end
 
   ##
@@ -803,21 +929,21 @@ class RDoc::Context < RDoc::CodeObject
     # look for a class or module 'symbol'
     case symbol
     when /^::/ then
-      result = RDoc::TopLevel.find_class_or_module(symbol)
+      result = @store.find_class_or_module symbol
     when /^(\w+):+(.+)$/
       suffix = $2
       top = $1
       searched = self
-      loop do
+      while searched do
         mod = searched.find_module_named(top)
         break unless mod
-        result = RDoc::TopLevel.find_class_or_module(mod.full_name + '::' + suffix)
+        result = @store.find_class_or_module "#{mod.full_name}::#{suffix}"
         break if result || searched.is_a?(RDoc::TopLevel)
         searched = searched.parent
       end
     else
       searched = self
-      loop do
+      while searched do
         result = searched.find_module_named(symbol)
         break if result || searched.is_a?(RDoc::TopLevel)
         searched = searched.parent
@@ -867,15 +993,28 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Instance methods
 
+  def instance_methods
+    @instance_methods ||= method_list.reject { |a| a.singleton }
+  end
+
+  ##
+  # Instance methods
+  #--
+  # TODO remove this later
+
   def instance_method_list
-    @instance_method_list ||= method_list.reject { |a| a.singleton }
+    warn '#instance_method_list is obsoleted, please use #instance_methods'
+    @instance_methods ||= method_list.reject { |a| a.singleton }
   end
 
   ##
-  # Breaks method_list into a nested hash by type (class or instance) and
-  # visibility (public, protected, private)
+  # Breaks method_list into a nested hash by type (<tt>'class'</tt> or
+  # <tt>'instance'</tt>) and visibility (+:public+, +:protected+, +:private+).
+  #
+  # If +section+ is provided only methods in that RDoc::Context::Section will
+  # be returned.
 
-  def methods_by_type
+  def methods_by_type section = nil
     methods = {}
 
     TYPES.each do |type|
@@ -888,6 +1027,7 @@ class RDoc::Context < RDoc::CodeObject
     end
 
     each_method do |method|
+      next if section and not method.section == section
       methods[method.type][method.visibility] << method
     end
 
@@ -897,10 +1037,14 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Yields AnyMethod and Attr entries matching the list of names in +methods+.
 
-  def methods_matching(methods, singleton = false)
+  def methods_matching(methods, singleton = false, &block)
     (@method_list + @attributes).each do |m|
       yield m if methods.include?(m.name) and m.singleton == singleton
     end
+
+    each_ancestor do |parent|
+      parent.methods_matching(methods, singleton, &block)
+    end
   end
 
   ##
@@ -962,25 +1106,33 @@ class RDoc::Context < RDoc::CodeObject
   #--
   # TODO mark the visibility of attributes in the template (if not public?)
 
-  def remove_invisible(min_visibility)
-    return if min_visibility == :private
+  def remove_invisible min_visibility
+    return if [:private, :nodoc].include? min_visibility
     remove_invisible_in @method_list, min_visibility
     remove_invisible_in @attributes, min_visibility
+    remove_invisible_in @constants, min_visibility
   end
 
-  def remove_invisible_in(array, min_visibility) # :nodoc:
-    if min_visibility == :public
-      array.reject! { |e| e.visibility != :public }
+  ##
+  # Only called when min_visibility == :public or :private
+
+  def remove_invisible_in array, min_visibility # :nodoc:
+    if min_visibility == :public then
+      array.reject! { |e|
+        e.visibility != :public and not e.force_documentation
+      }
     else
-      array.reject! { |e| e.visibility == :private }
+      array.reject! { |e|
+        e.visibility == :private and not e.force_documentation
+      }
     end
   end
 
   ##
-  # Tries to resolve unmatched aliases when a method
-  # or attribute has just been added.
+  # Tries to resolve unmatched aliases when a method or attribute has just
+  # been added.
 
-  def resolve_aliases(added)
+  def resolve_aliases added
     # resolve any pending unmatched aliases
     key = added.pretty_name
     unmatched_alias_list = @unmatched_alias_lists[key]
@@ -993,11 +1145,46 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
-  # Creates a new section with +title+ and +comment+
+  # Returns RDoc::Context::Section objects referenced in this context for use
+  # in a table of contents.
+
+  def section_contents
+    used_sections = {}
+
+    each_method do |method|
+      next unless method.display?
+
+      used_sections[method.section] = true
+    end
+
+    # order found sections
+    sections = sort_sections.select do |section|
+      used_sections[section]
+    end
+
+    # only the default section is used
+    return [] if
+      sections.length == 1 and not sections.first.title
+
+    sections
+  end
+
+  ##
+  # Sections in this context
+
+  def sections
+    @sections.values
+  end
 
-  def set_current_section(title, comment)
-    @current_section = Section.new self, title, comment
-    @sections << @current_section
+  def sections_hash # :nodoc:
+    @sections
+  end
+
+  ##
+  # Sets the current section to a section with +title+.  See also #add_section
+
+  def set_current_section title, comment
+    @current_section = add_section title, comment
   end
 
   ##
@@ -1010,6 +1197,37 @@ class RDoc::Context < RDoc::CodeObject
     end
   end
 
+  ##
+  # Given an array +names+ of constants, set the visibility of each constant to
+  # +visibility+
+
+  def set_constant_visibility_for(names, visibility)
+    names.each do |name|
+      constant = @constants_hash[name] or next
+      constant.visibility = visibility
+    end
+  end
+
+  ##
+  # Sorts sections alphabetically (default) or in TomDoc fashion (none,
+  # Public, Internal, Deprecated)
+
+  def sort_sections
+    titles = @sections.map { |title, _| title }
+
+    if titles.length > 1 and
+       TOMDOC_TITLES_SORT ==
+         (titles | TOMDOC_TITLES).sort_by { |title| title.to_s } then
+      @sections.values_at(*TOMDOC_TITLES).compact
+    else
+      @sections.sort_by { |title, _|
+        title.to_s
+      }.map { |_, section|
+        section
+      }
+    end
+  end
+
   def to_s # :nodoc:
     "#{self.class.name} #{self.full_name}"
   end
@@ -1034,13 +1252,15 @@ class RDoc::Context < RDoc::CodeObject
     enclosing.modules_hash.delete mod.name
 
     klass = RDoc::ClassModule.from_module class_type, mod
+    klass.store = @store
 
     # if it was there, then we keep it even if done_documenting
-    RDoc::TopLevel.classes_hash[mod.full_name] = klass
-    enclosing.classes_hash[mod.name]           = klass
+    @store.classes_hash[mod.full_name] = klass
+    enclosing.classes_hash[mod.name]   = klass
 
     klass
   end
 
-end
+  autoload :Section, 'rdoc/context/section'
 
+end