gitlab-rdoc 6.3.2

data/lib/rdoc/constant.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+##
+# A constant
+
+class RDoc::Constant < RDoc::CodeObject
+
+  MARSHAL_VERSION = 0 # :nodoc:
+
+  ##
+  # Sets the module or class this is constant is an alias for.
+
+  attr_writer :is_alias_for
+
+  ##
+  # The constant's name
+
+  attr_accessor :name
+
+  ##
+  # The constant's value
+
+  attr_accessor :value
+
+  ##
+  # The constant's visibility
+
+  attr_accessor :visibility
+
+  ##
+  # Creates a new constant with +name+, +value+ and +comment+
+
+  def initialize(name, value, comment)
+    super()
+
+    @name  = name
+    @value = value
+
+    @is_alias_for = nil
+    @visibility   = :public
+
+    self.comment = comment
+  end
+
+  ##
+  # Constants are ordered by name
+
+  def <=> other
+    return unless self.class === other
+
+    [parent_name, name] <=> [other.parent_name, other.name]
+  end
+
+  ##
+  # Constants are equal when their #parent and #name is the same
+
+  def == other
+    self.class == other.class and
+      @parent == other.parent and
+      @name == other.name
+  end
+
+  ##
+  # A constant is documented if it has a comment, or is an alias
+  # for a documented class or module.
+
+  def documented?
+    return true if super
+    return false unless @is_alias_for
+    case @is_alias_for
+    when String then
+      found = @store.find_class_or_module @is_alias_for
+      return false unless found
+      @is_alias_for = found
+    end
+    @is_alias_for.documented?
+  end
+
+  ##
+  # Full constant name including namespace
+
+  def full_name
+    @full_name ||= "#{parent_name}::#{@name}"
+  end
+
+  ##
+  # The module or class this constant is an alias for
+
+  def is_alias_for
+    case @is_alias_for
+    when String then
+      found = @store.find_class_or_module @is_alias_for
+      @is_alias_for = found if found
+      @is_alias_for
+    else
+      @is_alias_for
+    end
+  end
+
+  def inspect # :nodoc:
+    "#<%s:0x%x %s::%s>" % [
+      self.class, object_id,
+      parent_name, @name,
+    ]
+  end
+
+  ##
+  # Dumps this Constant for use by ri.  See also #marshal_load
+
+  def marshal_dump
+    alias_name = case found = is_alias_for
+                 when RDoc::CodeObject then found.full_name
+                 else                       found
+                 end
+
+    [ MARSHAL_VERSION,
+      @name,
+      full_name,
+      @visibility,
+      alias_name,
+      parse(@comment),
+      @file.relative_name,
+      parent.name,
+      parent.class,
+      section.title,
+    ]
+  end
+
+  ##
+  # Loads this Constant from +array+.  For a loaded Constant the following
+  # methods will return cached values:
+  #
+  # * #full_name
+  # * #parent_name
+
+  def marshal_load array
+    initialize array[1], nil, array[5]
+
+    @full_name     = array[2]
+    @visibility    = array[3] || :public
+    @is_alias_for  = array[4]
+    #                      5 handled above
+    #                      6 handled below
+    @parent_name   = array[7]
+    @parent_class  = array[8]
+    @section_title = array[9]
+
+    @file = RDoc::TopLevel.new array[6]
+  end
+
+  ##
+  # Path to this constant for use with HTML generator output.
+
+  def path
+    "#{@parent.path}##{@name}"
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, "[#{self.class.name} #{full_name}", "]" do
+      unless comment.empty? then
+        q.breakable
+        q.text "comment:"
+        q.breakable
+        q.pp @comment
+      end
+    end
+  end
+
+  ##
+  # Sets the store for this class or module and its contained code objects.
+
+  def store= store
+    super
+
+    @file = @store.add_file @file.full_name if @file
+  end
+
+  def to_s # :nodoc:
+    parent_name = parent ? parent.full_name : '(unknown)'
+    if is_alias_for
+      "constant #{parent_name}::#@name -> #{is_alias_for}"
+    else
+      "constant #{parent_name}::#@name"
+    end
+  end
+
+end
+

data/lib/rdoc/context/section.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+##
+# A section of documentation like:
+#
+#   # :section: The title
+#   # The body
+#
+# Sections can be referenced multiple times and will be collapsed into a
+# single section.
+
+class RDoc::Context::Section
+
+  include RDoc::Text
+
+  MARSHAL_VERSION = 0 # :nodoc:
+
+  ##
+  # Section comment
+
+  attr_reader :comment
+
+  ##
+  # Section comments
+
+  attr_reader :comments
+
+  ##
+  # Context this Section lives in
+
+  attr_reader :parent
+
+  ##
+  # Section title
+
+  attr_reader :title
+
+  ##
+  # Creates a new section with +title+ and +comment+
+
+  def initialize parent, title, comment
+    @parent = parent
+    @title = title ? title.strip : title
+
+    @comments = []
+
+    add_comment comment
+  end
+
+  ##
+  # Sections are equal when they have the same #title
+
+  def == other
+    self.class === other and @title == other.title
+  end
+
+  alias eql? ==
+
+  ##
+  # Adds +comment+ to this section
+
+  def add_comment comment
+    comment = extract_comment comment
+
+    return if comment.empty?
+
+    case comment
+    when RDoc::Comment then
+      @comments << comment
+    when RDoc::Markup::Document then
+      @comments.concat comment.parts
+    when Array then
+      @comments.concat comment
+    else
+      raise TypeError, "unknown comment type: #{comment.inspect}"
+    end
+  end
+
+  ##
+  # Anchor reference for linking to this section
+
+  def aref
+    title = @title || '[untitled]'
+
+    CGI.escape(title).gsub('%', '-').sub(/^-/, '')
+  end
+
+  ##
+  # Extracts 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 extract_comment comment
+    case comment
+    when Array then
+      comment.map do |c|
+        extract_comment c
+      end
+    when nil
+      RDoc::Comment.new ''
+    when RDoc::Comment then
+      if comment.text =~ /^#[ \t]*:section:.*\n/ then
+        start = $`
+        rest = $'
+
+        comment.text = if start.empty? then
+                         rest
+                       else
+                         rest.sub(/#{start.chomp}\Z/, '')
+                       end
+      end
+
+      comment
+    when RDoc::Markup::Document then
+      comment
+    else
+      raise TypeError, "unknown comment #{comment.inspect}"
+    end
+  end
+
+  def inspect # :nodoc:
+    "#<%s:0x%x %p>" % [self.class, object_id, title]
+  end
+
+  def hash # :nodoc:
+    @title.hash
+  end
+
+  ##
+  # The files comments in this section come from
+
+  def in_files
+    return [] if @comments.empty?
+
+    case @comments
+    when Array then
+      @comments.map do |comment|
+        comment.file
+      end
+    when RDoc::Markup::Document then
+      @comment.parts.map do |document|
+        document.file
+      end
+    else
+      raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
+    end
+  end
+
+  ##
+  # Serializes this Section.  The title and parsed comment are saved, but not
+  # the section parent which must be restored manually.
+
+  def marshal_dump
+    [
+      MARSHAL_VERSION,
+      @title,
+      parse,
+    ]
+  end
+
+  ##
+  # De-serializes this Section.  The section parent must be restored manually.
+
+  def marshal_load array
+    @parent  = nil
+
+    @title    = array[1]
+    @comments = array[2]
+  end
+
+  ##
+  # Parses +comment_location+ into an RDoc::Markup::Document composed of
+  # multiple RDoc::Markup::Documents with their file set.
+
+  def parse
+    case @comments
+    when String then
+      super
+    when Array then
+      docs = @comments.map do |comment, location|
+        doc = super comment
+        doc.file = location if location
+        doc
+      end
+
+      RDoc::Markup::Document.new(*docs)
+    when RDoc::Comment then
+      doc = super @comments.text, comments.format
+      doc.file = @comments.location
+      doc
+    when RDoc::Markup::Document then
+      return @comments
+    else
+      raise ArgumentError, "unknown comment class #{comments.class}"
+    end
+  end
+
+  ##
+  # The section's title, or 'Top Section' if the title is nil.
+  #
+  # This is used by the table of contents template so the name is silly.
+
+  def plain_html
+    @title || 'Top Section'
+  end
+
+  ##
+  # Removes a comment from this section if it is from the same file as
+  # +comment+
+
+  def remove_comment comment
+    return if @comments.empty?
+
+    case @comments
+    when Array then
+      @comments.delete_if do |my_comment|
+        my_comment.file == comment.file
+      end
+    when RDoc::Markup::Document then
+      @comments.parts.delete_if do |document|
+        document.file == comment.file.name
+      end
+    else
+      raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
+    end
+  end
+
+end
+

data/lib/rdoc/context.rb

@@ -0,0 +1,1266 @@
+# frozen_string_literal: true
+require 'cgi'
+
+##
+# A Context is something that can hold modules, classes, methods, attributes,
+# aliases, requires, and includes. Classes, modules, and files are all
+# Contexts.
+
+class RDoc::Context < RDoc::CodeObject
+
+  include Comparable
+
+  ##
+  # Types of methods
+
+  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
+
+  attr_reader :aliases
+
+  ##
+  # All attr* methods
+
+  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
+
+  ##
+  # Sets the current documentation section of documentation
+
+  attr_writer :current_section
+
+  ##
+  # Files this context is found in
+
+  attr_reader :in_files
+
+  ##
+  # Modules this context includes
+
+  attr_reader :includes
+
+  ##
+  # Modules this context is extended with
+
+  attr_reader :extends
+
+  ##
+  # Methods defined in this context
+
+  attr_reader :method_list
+
+  ##
+  # Name of this class excluding namespace.  See also full_name
+
+  attr_reader :name
+
+  ##
+  # Files this context requires
+
+  attr_reader :requires
+
+  ##
+  # Use this section for the next method, attribute or constant added.
+
+  attr_accessor :temporary_section
+
+  ##
+  # Hash <tt>old_name => [aliases]</tt>, for aliases
+  # that haven't (yet) been resolved to a method/attribute.
+  # (Not to be confused with the aliases of the context.)
+
+  attr_accessor :unmatched_alias_lists
+
+  ##
+  # Aliases that could not be resolved.
+
+  attr_reader :external_aliases
+
+  ##
+  # Current visibility of this context
+
+  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.
+
+  attr_reader :methods_hash
+
+  ##
+  # Params to be used in the next MethodAttr parsed under this context
+
+  attr_accessor :params
+
+  ##
+  # Hash of registered constants.
+
+  attr_reader :constants_hash
+
+  ##
+  # Creates an unnamed empty context with public current visibility
+
+  def initialize
+    super
+
+    @in_files = []
+
+    @name    ||= "unknown"
+    @parent  = nil
+    @visibility = :public
+
+    @current_section = Section.new self, nil, nil
+    @sections = { nil => @current_section }
+    @temporary_section = nil
+
+    @classes = {}
+    @modules = {}
+
+    initialize_methods_etc
+  end
+
+  ##
+  # Sets the defaults for methods and so-forth
+
+  def initialize_methods_etc
+    @method_list = []
+    @attributes  = []
+    @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   = {}
+    @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
+
+  def add_alias an_alias
+    return an_alias unless @document_self
+
+    method_attr = find_method(an_alias.old_name, an_alias.singleton) ||
+                  find_attribute(an_alias.old_name, an_alias.singleton)
+
+    if method_attr then
+      method_attr.add_alias an_alias, self
+    else
+      add_to @external_aliases, an_alias
+      unmatched_alias_list =
+        @unmatched_alias_lists[an_alias.pretty_old_name] ||= []
+      unmatched_alias_list.push an_alias
+    end
+
+    an_alias
+  end
+
+  ##
+  # Adds +attribute+ if not already there. If it is (as method(s) or attribute),
+  # updates the comment if it was empty.
+  #
+  # The attribute is registered only if it defines a new method.
+  # For instance, <tt>attr_reader :foo</tt> will not be registered
+  # if method +foo+ exists, but <tt>attr_accessor :foo</tt> will be registered
+  # if method +foo+ exists, but <tt>foo=</tt> does not.
+
+  def add_attribute attribute
+    return attribute unless @document_self
+
+    # mainly to check for redefinition of an attribute as a method
+    # TODO find a policy for 'attr_reader :foo' + 'def foo=()'
+    register = false
+
+    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' 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 register then
+      attribute.visibility = @visibility
+      add_to @attributes, attribute
+      resolve_aliases attribute
+    end
+
+    attribute
+  end
+
+  ##
+  # Adds a class named +given_name+ with +superclass+.
+  #
+  # Both +given_name+ and +superclass+ may contain '::', and are
+  # interpreted relative to the +self+ context. This allows handling correctly
+  # examples like these:
+  #   class RDoc::Gauntlet < Gauntlet
+  #   module Mod
+  #     class Object   # implies < ::Object
+  #     class SubObject < Object  # this is _not_ ::Object
+  #
+  # Given <tt>class Container::Item</tt> RDoc assumes +Container+ is a module
+  # unless it later sees <tt>class Container</tt>.  +add_class+ automatically
+  # upgrades +given_name+ to a class in this case.
+
+  def add_class class_type, given_name, superclass = '::Object'
+    # superclass +nil+ is passed by the C parser in the following cases:
+    # - registering Object in 1.8 (correct)
+    # - registering BasicObject in 1.9 (correct)
+    # - registering RubyVM in 1.9 in iseq.c (incorrect: < Object in vm.c)
+    #
+    # If we later find a superclass for a registered class with a nil
+    # superclass, we must honor it.
+
+    # find the name & enclosing context
+    if given_name =~ /^:+(\w+)$/ then
+      full_name = $1
+      enclosing = top_level
+      name = full_name.split(/:+/).last
+    else
+      full_name = child_name given_name
+
+      if full_name =~ /^(.+)::(\w+)$/ then
+        name = $2
+        ename = $1
+        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 = @store.classes_hash[given_name] ||
+                      @store.modules_hash[given_name]
+          return enclosing if enclosing
+          # not found: create the parent(s)
+          names = ename.split('::')
+          enclosing = self
+          names.each do |n|
+            enclosing = enclosing.classes_hash[n] ||
+                        enclosing.modules_hash[n] ||
+                        enclosing.add_module(RDoc::NormalModule, n)
+          end
+        end
+      else
+        name = full_name
+        enclosing = self
+      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
+        superclass = $' #'
+      else
+        if superclass =~ /^(\w+):+(.+)$/ then
+          suffix = $2
+          mod = find_module_named($1)
+          superclass = mod.full_name + '::' + suffix if mod
+        else
+          mod = find_module_named(superclass)
+          superclass = mod.full_name if mod
+        end
+      end
+
+      # did we believe it was a module?
+      mod = @store.modules_hash.delete superclass
+
+      upgrade_to_class mod, RDoc::NormalClass, mod.parent if mod
+
+      # e.g., Object < Object
+      superclass = nil if superclass == full_name
+    end
+
+    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
+        existing = existing.full_name unless existing.is_a?(String) if existing
+        if existing.nil? ||
+           (existing == 'Object' && superclass != 'Object') then
+          klass.superclass = superclass
+        end
+      end
+    else
+      # this is a new class
+      mod = @store.modules_hash.delete full_name
+
+      if mod then
+        klass = upgrade_to_class mod, RDoc::NormalClass, enclosing
+
+        klass.superclass = superclass unless superclass.nil?
+      else
+        klass = class_type.new name, superclass
+
+        enclosing.add_class_or_module(klass, enclosing.classes_hash,
+                                      @store.classes_hash)
+      end
+    end
+
+    klass.parent = self
+
+    klass
+  end
+
+  ##
+  # Adds the class or module +mod+ to the modules or
+  # classes Hash +self_hash+, and to +all_hash+ (either
+  # <tt>TopLevel::modules_hash</tt> or <tt>TopLevel::classes_hash</tt>),
+  # unless #done_documenting is +true+. Sets the #parent of +mod+
+  # 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.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
+  end
+
+  ##
+  # 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
+    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 then
+      known.comment = constant.comment if known.comment.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
+    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
+    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 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
+      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
+
+  ##
+  # Adds a module named +name+.  If RDoc already knows +name+ is a class then
+  # that class is returned instead.  See also #add_class.
+
+  def add_module(class_type, name)
+    mod = @classes[name] || @modules[name]
+    return mod if mod
+
+    full_name = child_name name
+    mod = @store.modules_hash[full_name] || class_type.new(name)
+
+    add_class_or_module mod, @modules, @store.modules_hash
+  end
+
+  ##
+  # Adds a module by +RDoc::NormalModule+ instance. See also #add_module.
+
+  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_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 is a class when we find
+    # BasicObject = BlankSlate
+    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
+
+    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
+      @store.classes_hash[to_full_name] = new_to
+      @classes[to.name] = new_to
+    end
+
+    # 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
+
+    new_to
+  end
+
+  ##
+  # Adds +require+ to this context's top level
+
+  def add_require(require)
+    return require unless @document_self
+
+    if RDoc::TopLevel === self then
+      add_to @requires, require
+    else
+      parent.add_require require
+    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
+    array << thing if @document_self
+
+    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 and extends are also checked unless <tt>includes == false</tt>.
+
+  def any_content(includes = true)
+    @any_content ||= !(
+      @comment.empty? &&
+      @method_list.empty? &&
+      @attributes.empty? &&
+      @aliases.empty? &&
+      @external_aliases.empty? &&
+      @requires.empty? &&
+      @constants.empty?
+    )
+    @any_content || (includes && !(@includes + @extends).empty? )
+  end
+
+  ##
+  # Creates the full name for a child with +name+
+
+  def child_name name
+    if name =~ /^:+/
+      $'  #'
+    elsif RDoc::TopLevel === self then
+      name
+    else
+      "#{self.full_name}::#{name}"
+    end
+  end
+
+  ##
+  # Class attributes
+
+  def class_attributes
+    @class_attributes ||= attributes.select { |a| a.singleton }
+  end
+
+  ##
+  # Class methods
+
+  def class_method_list
+    @class_method_list ||= method_list.select { |a| a.singleton }
+  end
+
+  ##
+  # Array of classes in this context
+
+  def classes
+    @classes.values
+  end
+
+  ##
+  # All classes and modules in this namespace
+
+  def classes_and_modules
+    classes + modules
+  end
+
+  ##
+  # Hash of classes keyed by class name
+
+  def classes_hash
+    @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+?
+
+  def defined_in?(file)
+    @in_files.include?(file)
+  end
+
+  def display(method_attr) # :nodoc:
+    if method_attr.is_a? RDoc::Attr
+      "#{method_attr.definition} #{method_attr.pretty_name}"
+    else
+      "method #{method_attr.pretty_name}"
+    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
+
+  def each_attribute # :yields: attribute
+    @attributes.each { |a| yield a }
+  end
+
+  ##
+  # Iterator for classes and modules
+
+  def each_classmodule(&block) # :yields: module
+    classes_and_modules.sort.each(&block)
+  end
+
+  ##
+  # Iterator for constants
+
+  def each_constant # :yields: constant
+    @constants.each {|c| yield c}
+  end
+
+  ##
+  # Iterator for included modules
+
+  def each_include # :yields: include
+    @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
+    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
+
+  ##
+  # Finds an attribute +name+ with singleton value +singleton+.
+
+  def find_attribute(name, singleton)
+    name = $1 if name =~ /^(.*)=$/
+    @attributes.find { |a| a.name == name && a.singleton == singleton }
+  end
+
+  ##
+  # Finds an attribute with +name+ in this context
+
+  def find_attribute_named(name)
+    case name
+    when /\A#/ then
+      find_attribute name[1..-1], false
+    when /\A::/ then
+      find_attribute name[2..-1], true
+    else
+      @attributes.find { |a| a.name == name }
+    end
+  end
+
+  ##
+  # Finds a class method with +name+ in this context
+
+  def find_class_method_named(name)
+    @method_list.find { |meth| meth.singleton && meth.name == name }
+  end
+
+  ##
+  # Finds a constant with +name+ in this context
+
+  def find_constant_named(name)
+    @constants.find do |m|
+      m.name == name || m.full_name == name
+    end
+  end
+
+  ##
+  # Find a module at a higher scope
+
+  def find_enclosing_module_named(name)
+    parent && parent.find_module_named(name)
+  end
+
+  ##
+  # Finds an external alias +name+ with singleton value +singleton+.
+
+  def find_external_alias(name, singleton)
+    @external_aliases.find { |m| m.name == name && m.singleton == singleton }
+  end
+
+  ##
+  # Finds an external alias with +name+ in this context
+
+  def find_external_alias_named(name)
+    case name
+    when /\A#/ then
+      find_external_alias name[1..-1], false
+    when /\A::/ then
+      find_external_alias name[2..-1], true
+    else
+      @external_aliases.find { |a| a.name == name }
+    end
+  end
+
+  ##
+  # Finds a file with +name+ in this context
+
+  def find_file_named name
+    @store.find_file_named name
+  end
+
+  ##
+  # Finds an instance method with +name+ in this context
+
+  def find_instance_method_named(name)
+    @method_list.find { |meth| !meth.singleton && meth.name == name }
+  end
+
+  ##
+  # Finds a method, constant, attribute, external alias, module or file
+  # named +symbol+ in this context.
+
+  def find_local_symbol(symbol)
+    find_method_named(symbol) or
+    find_constant_named(symbol) or
+    find_attribute_named(symbol) or
+    find_external_alias_named(symbol) or
+    find_module_named(symbol) or
+    find_file_named(symbol)
+  end
+
+  ##
+  # Finds a method named +name+ with singleton value +singleton+.
+
+  def find_method(name, singleton)
+    @method_list.find { |m|
+      if m.singleton
+        m.name == name && m.singleton == singleton
+      else
+        m.name == name && !m.singleton && !singleton
+      end
+    }
+  end
+
+  ##
+  # Finds a instance or module method with +name+ in this context
+
+  def find_method_named(name)
+    case name
+    when /\A#/ then
+      find_method name[1..-1], false
+    when /\A::/ then
+      find_method name[2..-1], true
+    else
+      @method_list.find { |meth| meth.name == name }
+    end
+  end
+
+  ##
+  # Find a module with +name+ using ruby's scoping rules
+
+  def find_module_named(name)
+    res = @modules[name] || @classes[name]
+    return res if res
+    return self if self.name == name
+    find_enclosing_module_named name
+  end
+
+  ##
+  # Look up +symbol+, first as a module, then as a local symbol.
+
+  def find_symbol(symbol)
+    find_symbol_module(symbol) || find_local_symbol(symbol)
+  end
+
+  ##
+  # Look up a module named +symbol+.
+
+  def find_symbol_module(symbol)
+    result = nil
+
+    # look for a class or module 'symbol'
+    case symbol
+    when /^::/ then
+      result = @store.find_class_or_module symbol
+    when /^(\w+):+(.+)$/
+      suffix = $2
+      top = $1
+      searched = self
+      while searched do
+        mod = searched.find_module_named(top)
+        break unless mod
+        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
+      while searched do
+        result = searched.find_module_named(symbol)
+        break if result || searched.is_a?(RDoc::TopLevel)
+        searched = searched.parent
+      end
+    end
+
+    result
+  end
+
+  ##
+  # The full name for this context.  This method is overridden by subclasses.
+
+  def full_name
+    '(unknown)'
+  end
+
+  ##
+  # Does this context and its methods and constants all have documentation?
+  #
+  # (Yes, fully documented doesn't mean everything.)
+
+  def fully_documented?
+    documented? and
+      attributes.all? { |a| a.documented? } and
+      method_list.all? { |m| m.documented? } and
+      constants.all? { |c| c.documented? }
+  end
+
+  ##
+  # URL for this with a +prefix+
+
+  def http_url(prefix)
+    path = name_for_path
+    path = path.gsub(/<<\s*(\w*)/, 'from-\1') if path =~ /<</
+    path = [prefix] + path.split('::')
+
+    File.join(*path.compact) + '.html'
+  end
+
+  ##
+  # Instance attributes
+
+  def instance_attributes
+    @instance_attributes ||= attributes.reject { |a| a.singleton }
+  end
+
+  ##
+  # Instance methods
+
+  def instance_methods
+    @instance_methods ||= method_list.reject { |a| a.singleton }
+  end
+
+  ##
+  # Instance methods
+  #--
+  # TODO remove this later
+
+  def instance_method_list
+    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 (<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 section = nil
+    methods = {}
+
+    TYPES.each do |type|
+      visibilities = {}
+      RDoc::VISIBILITIES.each do |vis|
+        visibilities[vis] = []
+      end
+
+      methods[type] = visibilities
+    end
+
+    each_method do |method|
+      next if section and not method.section == section
+      methods[method.type][method.visibility] << method
+    end
+
+    methods
+  end
+
+  ##
+  # Yields AnyMethod and Attr entries matching the list of names in +methods+.
+
+  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
+
+  ##
+  # Array of modules in this context
+
+  def modules
+    @modules.values
+  end
+
+  ##
+  # Hash of modules keyed by module name
+
+  def modules_hash
+    @modules
+  end
+
+  ##
+  # Name to use to generate the url.
+  # <tt>#full_name</tt> by default.
+
+  def name_for_path
+    full_name
+  end
+
+  ##
+  # Changes the visibility for new methods to +visibility+
+
+  def ongoing_visibility=(visibility)
+    @visibility = visibility
+  end
+
+  ##
+  # Record +top_level+ as a file +self+ is in.
+
+  def record_location(top_level)
+    @in_files << top_level unless @in_files.include?(top_level)
+  end
+
+  ##
+  # Should we remove this context from the documentation?
+  #
+  # The answer is yes if:
+  # * #received_nodoc is +true+
+  # * #any_content is +false+ (not counting includes)
+  # * All #includes are modules (not a string), and their module has
+  #   <tt>#remove_from_documentation? == true</tt>
+  # * All classes and modules have <tt>#remove_from_documentation? == true</tt>
+
+  def remove_from_documentation?
+    @remove_from_documentation ||=
+      @received_nodoc &&
+      !any_content(false) &&
+      @includes.all? { |i| !i.module.is_a?(String) && i.module.remove_from_documentation? } &&
+      classes_and_modules.all? { |cm| cm.remove_from_documentation? }
+  end
+
+  ##
+  # Removes methods and attributes with a visibility less than +min_visibility+.
+  #--
+  # TODO mark the visibility of attributes in the template (if not public?)
+
+  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
+
+  ##
+  # 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 and not e.force_documentation
+      }
+    end
+  end
+
+  ##
+  # Tries to resolve unmatched aliases when a method or attribute has just
+  # been added.
+
+  def resolve_aliases added
+    # resolve any pending unmatched aliases
+    key = added.pretty_name
+    unmatched_alias_list = @unmatched_alias_lists[key]
+    return unless unmatched_alias_list
+    unmatched_alias_list.each do |unmatched_alias|
+      added.add_alias unmatched_alias, self
+      @external_aliases.delete unmatched_alias
+    end
+    @unmatched_alias_lists.delete key
+  end
+
+  ##
+  # 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 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
+
+  ##
+  # Given an array +methods+ of method names, set the visibility of each to
+  # +visibility+
+
+  def set_visibility_for(methods, visibility, singleton = false)
+    methods_matching methods, singleton do |m|
+      m.visibility = visibility
+    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
+
+  ##
+  # Return the TopLevel that owns us
+  #--
+  # FIXME we can be 'owned' by several TopLevel (see #record_location &
+  # #in_files)
+
+  def top_level
+    return @top_level if defined? @top_level
+    @top_level = self
+    @top_level = @top_level.parent until RDoc::TopLevel === @top_level
+    @top_level
+  end
+
+  ##
+  # Upgrades NormalModule +mod+ in +enclosing+ to a +class_type+
+
+  def upgrade_to_class mod, class_type, enclosing
+    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
+    @store.classes_hash[mod.full_name] = klass
+    enclosing.classes_hash[mod.name]   = klass
+
+    klass
+  end
+
+  autoload :Section, 'rdoc/context/section'
+
+end