rdoc 7.2.0 → 8.1.0

data/lib/rdoc/code_object/context.rb

@@ -1,1233 +1,1206 @@
 # frozen_string_literal: true
-##
-# A Context is something that can hold modules, classes, methods, attributes,
-# aliases, requires, and includes. Classes, modules, and files are all
-# Contexts.
+module RDoc
+  ##
+  # 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
+  class Context < CodeObject
 
-  include Comparable
+    include Comparable
 
-  ##
-  # Types of methods
+    ##
+    # Types of methods
 
-  TYPES = %w[class instance]
+    TYPES = %w[class instance]
 
-  ##
-  # If a context has these titles it will be sorted in this order.
+    ##
+    # 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:
+    TOMDOC_TITLES = [nil, 'Public', 'Internal', 'Deprecated'] # :nodoc:
+    TOMDOC_TITLES_SORT = TOMDOC_TITLES.sort_by { |title| title.to_s } # :nodoc:
 
-  ##
-  # Class/module aliases
+    ##
+    # Class/module aliases
 
-  attr_reader :aliases
+    attr_reader :aliases
 
-  ##
-  # All attr* methods
+    ##
+    # All attr* methods
 
-  attr_reader :attributes
+    attr_reader :attributes
 
-  ##
-  # Block params to be used in the next MethodAttr parsed under this context
+    ##
+    # Block params to be used in the next MethodAttr parsed under this context
 
-  attr_accessor :block_params
+    attr_accessor :block_params
 
-  ##
-  # Constants defined
+    ##
+    # Constants defined
 
-  attr_reader :constants
+    attr_reader :constants
 
-  ##
-  # Sets the current documentation section of documentation
+    ##
+    # Sets the current documentation section of documentation
 
-  attr_writer :current_section
+    attr_writer :current_section
 
-  ##
-  # Files this context is found in
+    ##
+    # Files this context is found in
 
-  attr_reader :in_files
+    attr_reader :in_files
 
-  ##
-  # Modules this context includes
+    ##
+    # Modules this context includes
 
-  attr_reader :includes
+    attr_reader :includes
 
-  ##
-  # Modules this context is extended with
+    ##
+    # Modules this context is extended with
 
-  attr_reader :extends
+    attr_reader :extends
 
-  ##
-  # Methods defined in this context
+    ##
+    # Methods defined in this context
 
-  attr_reader :method_list
+    attr_reader :method_list
 
-  ##
-  # Name of this class excluding namespace.  See also full_name
+    ##
+    # Name of this class excluding namespace.  See also full_name
 
-  attr_reader :name
+    attr_reader :name
 
-  ##
-  # Files this context requires
+    ##
+    # Files this context requires
 
-  attr_reader :requires
-
-  ##
-  # Use this section for the next method, attribute or constant added.
+    attr_reader :requires
 
-  attr_accessor :temporary_section
+    ##
+    # Use this section for the next method, attribute or constant added.
 
-  ##
-  # 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 :temporary_section
 
-  attr_accessor :unmatched_alias_lists
+    ##
+    # 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.)
 
-  ##
-  # Aliases that could not be resolved.
+    attr_accessor :unmatched_alias_lists
 
-  attr_reader :external_aliases
+    ##
+    # Aliases that could not be resolved.
 
-  ##
-  # Current visibility of this context
+    attr_reader :external_aliases
 
-  attr_accessor :visibility
+    ##
+    # Hash of registered methods. Attributes are also registered here,
+    # twice if they are RW.
 
-  ##
-  # Current visibility of this line
+    attr_reader :methods_hash
 
-  attr_writer :current_line_visibility
+    ##
+    # Params to be used in the next MethodAttr parsed under this context
 
-  ##
-  # Hash of registered methods. Attributes are also registered here,
-  # twice if they are RW.
+    attr_accessor :params
 
-  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
+    ##
+    # Creates an unnamed empty context
 
-  ##
-  # Hash of registered constants.
+    def initialize
+      super
 
-  attr_reader :constants_hash
+      @in_files = []
 
-  ##
-  # Creates an unnamed empty context with public current visibility
+      @name    ||= "unknown"
+      @parent  = nil
+      @current_section = Section.new self, nil, nil
+      @sections = { nil => @current_section }
+      @temporary_section = nil
 
-  def initialize
-    super
+      @classes = {}
+      @modules = {}
 
-    @in_files = []
+      initialize_methods_etc
+    end
 
-    @name    ||= "unknown"
-    @parent  = nil
-    @visibility = :public
+    ##
+    # Sets the defaults for methods and so-forth
 
-    @current_section = Section.new self, nil, nil
-    @sections = { nil => @current_section }
-    @temporary_section = nil
+    def initialize_methods_etc
+      @method_list = []
+      @attributes  = []
+      @aliases     = []
+      @requires    = []
+      @includes    = []
+      @extends     = []
+      @constants   = []
+      @external_aliases = []
+      # This Hash maps a method name to a list of unmatched aliases (aliases of
+      # a method not yet encountered).
+      @unmatched_alias_lists = {}
 
-    @classes = {}
-    @modules = {}
+      @methods_hash   = {}
+      @constants_hash = {}
 
-    initialize_methods_etc
-  end
+      @params = nil
 
-  ##
-  # Sets the defaults for methods and so-forth
+      @store ||= nil
+    end
 
-  def initialize_methods_etc
-    @method_list = []
-    @attributes  = []
-    @aliases     = []
-    @requires    = []
-    @includes    = []
-    @extends     = []
-    @constants   = []
-    @external_aliases = []
-    @current_line_visibility = nil
+    ##
+    # Contexts are sorted by full_name
 
-    # This Hash maps a method name to a list of unmatched aliases (aliases of
-    # a method not yet encountered).
-    @unmatched_alias_lists = {}
+    def <=>(other)
+      return nil unless CodeObject === other
 
-    @methods_hash   = {}
-    @constants_hash = {}
+      full_name <=> other.full_name
+    end
 
-    @params = nil
+    ##
+    # 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 Extend == klass
+        ext = Extend.new name, comment
+        add_extend ext
+      elsif Include == klass
+        incl = Include.new name, comment
+        add_include incl
+      else
+        raise NotImplementedError, "adding a #{klass} is not implemented"
+      end
+    end
 
-    @store ||= nil
-  end
+    ##
+    # Adds +an_alias+ that is automatically resolved
 
-  ##
-  # Contexts are sorted by full_name
+    def add_alias(an_alias)
+      return an_alias unless @document_self
 
-  def <=>(other)
-    return nil unless RDoc::CodeObject === other
+      method_attr = find_method(an_alias.old_name, an_alias.singleton) ||
+                    find_attribute(an_alias.old_name, an_alias.singleton)
 
-    full_name <=> other.full_name
-  end
+      if method_attr
+        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
 
-  ##
-  # 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"
+      an_alias
     end
-  end
 
-  ##
-  # Adds +an_alias+ that is automatically resolved
+    ##
+    # 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_alias(an_alias)
-    return an_alias unless @document_self
+    def add_attribute(attribute)
+      return attribute unless @document_self
 
-    method_attr = find_method(an_alias.old_name, an_alias.singleton) ||
-                  find_attribute(an_alias.old_name, an_alias.singleton)
+      # mainly to check for redefinition of an attribute as a method
+      # TODO find a policy for 'attr_reader :foo' + 'def foo=()'
+      register = false
 
-    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
+      key = nil
 
-    an_alias
-  end
+      if attribute.rw.index 'R'
+        key = attribute.pretty_name
+        known = @methods_hash[key]
 
-  ##
-  # 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.
+        if known
+          known.comment = attribute.comment if known.comment.empty?
+        elsif registered = @methods_hash[attribute.pretty_name + '='] and
+              Attr === registered
+          registered.rw = 'RW'
+        else
+          @methods_hash[key] = attribute
+          register = true
+        end
+      end
 
-  def add_attribute(attribute)
-    return attribute unless @document_self
+      if attribute.rw.index 'W'
+        key = attribute.pretty_name + '='
+        known = @methods_hash[key]
 
-    # mainly to check for redefinition of an attribute as a method
-    # TODO find a policy for 'attr_reader :foo' + 'def foo=()'
-    register = false
+        if known
+          known.comment = attribute.comment if known.comment.empty?
+        elsif registered = @methods_hash[attribute.pretty_name] and
+              Attr === registered
+          registered.rw = 'RW'
+        else
+          @methods_hash[key] = attribute
+          register = true
+        end
+      end
 
-    key = nil
+      if register
+        add_to @attributes, attribute
+        resolve_aliases attribute
+      end
 
-    if attribute.rw.index 'R' then
-      key = attribute.pretty_name
-      known = @methods_hash[key]
+      attribute
+    end
 
-      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'
+    ##
+    # 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+)$/
+        full_name = $1
+        enclosing = top_level
+        name = full_name.split(/:+/).last
       else
-        @methods_hash[key] = attribute
-        register = true
+        full_name = child_name given_name
+
+        if full_name =~ /^(.+)::(\w+)$/
+          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
+            # 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)
+            enclosing = find_or_create_namespace_path ename
+          end
+        else
+          name = full_name
+          enclosing = self
+        end
       end
-    end
 
-    if attribute.rw.index 'W' then
-      key = attribute.pretty_name + '='
-      known = @methods_hash[key]
+      # fix up superclass
+      if full_name == 'BasicObject'
+        superclass = nil
+      elsif full_name == 'Object'
+        superclass = '::BasicObject'
+      end
 
-      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
+      # find the superclass full name
+      if superclass
+        if superclass =~ /^:+/
+          superclass = $' #'
+        else
+          if superclass =~ /^(\w+):+(.+)$/
+            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, NormalClass, mod.parent if mod
+
+        # e.g., Object < Object
+        superclass = nil if superclass == full_name
       end
-    end
 
-    if register then
-      attribute.visibility = @visibility
-      add_to @attributes, attribute
-      resolve_aliases attribute
-    end
+      klass = @store.classes_hash[full_name]
 
-    attribute
-  end
+      if klass
+        # if TopLevel, it may not be registered in the classes:
+        enclosing.classes_hash[name] = klass
 
-  ##
-  # 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)
+        # update the superclass if needed
+        if superclass
+          existing = klass.superclass
+          existing = existing.full_name unless existing.is_a?(String) if existing
+          if existing.nil? ||
+             (existing == 'Object' && superclass != 'Object')
+            klass.superclass = superclass
           end
         end
       else
-        name = full_name
-        enclosing = self
-      end
-    end
+        # this is a new class
+        mod = @store.modules_hash.delete full_name
 
-    # fix up superclass
-    if full_name == 'BasicObject' then
-      superclass = nil
-    elsif full_name == 'Object' then
-      superclass = '::BasicObject'
-    end
+        if mod
+          klass = upgrade_to_class mod, NormalClass, enclosing
 
-    # 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
+          klass.superclass = superclass unless superclass.nil?
         else
-          mod = find_module_named(superclass)
-          superclass = mod.full_name if mod
+          klass = class_type.new name, superclass
+
+          enclosing.add_class_or_module(klass, enclosing.classes_hash,
+                                        @store.classes_hash)
         end
       end
 
-      # did we believe it was a module?
-      mod = @store.modules_hash.delete superclass
+      klass.parent = self
 
-      upgrade_to_class mod, RDoc::NormalClass, mod.parent if mod
+      klass
+    end
 
-      # e.g., Object < Object
-      superclass = nil if superclass == full_name
+    ##
+    # 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
+        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
+      end
+
+      mod
     end
 
-    klass = @store.classes_hash[full_name]
+    ##
+    # 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.
 
-    if klass then
-      # if TopLevel, it may not be registered in the classes:
-      enclosing.classes_hash[name] = klass
+    def add_constant(constant)
+      return constant unless @document_self
 
-      # 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
+      # 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 mod then
-        klass = upgrade_to_class mod, RDoc::NormalClass, enclosing
+      if known
+        known.comment = constant.comment if known.comment.empty?
 
-        klass.superclass = superclass unless superclass.nil?
-      else
-        klass = class_type.new name, superclass
+        known.value = constant.value if
+          known.value.nil? or known.value.strip.empty?
 
-        enclosing.add_class_or_module(klass, enclosing.classes_hash,
-                                      @store.classes_hash)
+        constant.parent = self
+        known.is_alias_for ||= constant.is_alias_for
+      else
+        @constants_hash[constant.name] = constant
+        add_to @constants, constant
       end
+
+      constant
     end
 
-    klass.parent = self
+    ##
+    # Adds included module +include+ which should be an RDoc::Include
 
-    klass
-  end
+    def add_include(include)
+      add_to @includes, include
 
-  ##
-  # 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
+      include
     end
 
-    mod
-  end
+    ##
+    # Adds extension module +ext+ which should be an RDoc::Extend
 
-  ##
-  # 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_extend(ext)
+      add_to @extends, ext
 
-  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]
+      ext
+    end
 
-    if known then
-      known.comment = constant.comment if known.comment.empty?
+    ##
+    # Adds +method+ if not already there. If it is (as method or attribute),
+    # updates the comment if it was empty.
 
-      known.value = constant.value if
-        known.value.nil? or known.value.strip.empty?
+    def add_method(method)
+      return method unless @document_self
 
-      known.is_alias_for ||= constant.is_alias_for
-    else
-      @constants_hash[constant.name] = constant
-      add_to @constants, constant
-    end
+      # HACK: avoid duplicate 'new' in io.c & struct.c (1.8.7 source code)
+      key = method.pretty_name
+      known = @methods_hash[key]
 
-    constant
-  end
+      if known
+        if @store # otherwise we are loading
+          known.comment = method.comment if known.comment.empty?
+          previously = ", previously in #{known.file}" unless
+            method.file == known.file
+          @store.options.warn \
+            "Duplicate method #{known.full_name} in #{method.file}#{previously}"
+        end
+      else
+        @methods_hash[key] = method
+        add_to @method_list, method
+        resolve_aliases method
+      end
 
-  ##
-  # Adds included module +include+ which should be an RDoc::Include
+      method
+    end
 
-  def add_include(include)
-    add_to @includes, include
+    ##
+    # Returns the owner context and local name for +constant_path+, creating
+    # missing namespace modules. A leading +::+ resolves from the top-level.
+    # This only resolves explicit context-tree paths; RDoc::Parser::Ruby has
+    # parser-local lexical helpers for Ruby's nesting-dependent lookup.
 
-    include
-  end
+    def find_or_create_constant_owner_for_path(constant_path) # :nodoc:
+      constant_path = constant_path.to_s
+      owner = constant_path.start_with?('::') ? top_level : self
+      constant_path = constant_path.delete_prefix('::')
 
-  ##
-  # Adds extension module +ext+ which should be an RDoc::Extend
+      owner_path, separator, name = constant_path.rpartition('::')
+      owner = owner.find_or_create_namespace_path owner_path unless separator.empty?
 
-  def add_extend(ext)
-    add_to @extends, ext
+      [owner, name]
+    end
 
-    ext
-  end
+    ##
+    # Finds or creates the module namespace path under this context.
 
-  ##
-  # 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.options.warn \
-          "Duplicate method #{known.full_name} in #{method.file}#{previously}"
+    def find_or_create_namespace_path(path) # :nodoc:
+      path.to_s.split('::').inject(self) do |owner, name|
+        owner.classes_hash[name] ||
+          owner.modules_hash[name] ||
+          owner.add_module(NormalModule, name)
       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.
 
-  ##
-  # 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)
+      if name.to_s.include?('::')
+        owner, name = find_or_create_constant_owner_for_path name
+        return owner.add_module class_type, name unless owner == self
+      end
 
-  def add_module(class_type, name)
-    mod = @classes[name] || @modules[name]
-    return mod if mod
+      mod = @classes[name] || @modules[name]
+      return mod if mod
 
-    full_name = child_name name
-    mod = @store.modules_hash[full_name] || class_type.new(name)
+      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
+      add_class_or_module mod, @modules, @store.modules_hash
+    end
 
-  ##
-  # Adds a module by +RDoc::NormalModule+ instance. See also #add_module.
+    ##
+    # 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
+    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+.
+    ##
+    # Adds an alias from +from+ (a class or module) to the constant +to+ which
+    # was defined in +file+.
 
-  def add_module_alias(from, from_name, to, file)
-    return from if @done_documenting
+    def add_module_alias(from, to, file)
+      return from if @done_documenting
 
-    to_full_name = child_name to.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 is a class when we find
-    # BasicObject = BlankSlate
-    return from if @store.find_class_or_module to_full_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
+      new_to.is_alias_for = from
 
-    new_to = from.dup
-    new_to.name = to.name
-    new_to.full_name = nil
+      if new_to.module?
+        @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
 
-    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
+      # Registers a constant for this alias.  The constant value and comment
+      # will be updated later, when the Ruby parser adds the constant
+      const = Constant.new to.name, nil, new_to.comment
+      const.record_location file
+      const.is_alias_for = from
+      add_constant const
+
+      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
+    ##
+    # Adds +require+ to this context's top level
 
-    new_to
-  end
+    def add_require(require)
+      return require unless @document_self
 
-  ##
-  # Adds +require+ to this context's top level
+      if TopLevel === self
+        add_to @requires, require
+      else
+        parent.add_require require
+      end
+    end
 
-  def add_require(require)
-    return require unless @document_self
+    ##
+    # 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
 
-    if RDoc::TopLevel === self then
-      add_to @requires, require
-    else
-      parent.add_require require
+    def add_section(title, comment = nil)
+      if section = @sections[title]
+        section.add_comment comment if comment
+      else
+        section = Section.new self, title, comment, @store
+        @sections[title] = section
+      end
+
+      section
     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, @store
-      @sections[title] = section
-    end
-
-    section
-  end
+    ##
+    # Adds +thing+ to the collection +array+
 
-  ##
-  # Adds +thing+ to the collection +array+
+    def add_to(array, thing)
+      array << thing if @document_self
 
-  def add_to(array, thing)
-    array << thing if @document_self
+      thing.parent  = self
+      thing.store   = @store if @store
+      thing.section = current_section
+    end
 
-    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
 
-  ##
-  # 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+
 
-  ##
-  # 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}"
+    def child_name(name)
+      if name =~ /^:+/
+        $'  #'
+      elsif TopLevel === self
+        name
+      else
+        "#{self.full_name}::#{name}"
+      end
     end
-  end
 
-  ##
-  # Class attributes
+    ##
+    # Class methods
 
-  def class_attributes
-    @class_attributes ||= attributes.select { |a| a.singleton }
-  end
+    def class_method_list
+      method_list.select { |a| a.singleton }
+    end
 
-  ##
-  # Class methods
+    ##
+    # Array of classes in this context
 
-  def class_method_list
-    @class_method_list ||= method_list.select { |a| a.singleton }
-  end
+    def classes
+      @classes.values
+    end
 
-  ##
-  # Array of classes in this context
+    ##
+    # All classes and modules in this namespace
 
-  def classes
-    @classes.values
-  end
+    def classes_and_modules
+      classes + modules
+    end
 
-  ##
-  # All classes and modules in this namespace
+    ##
+    # Hash of classes keyed by class name
 
-  def classes_and_modules
-    classes + modules
-  end
+    def classes_hash
+      @classes
+    end
 
-  ##
-  # Hash of classes keyed by class name
+    ##
+    # The current documentation section that new items will be added to.  If
+    # temporary_section is available it will be used.
 
-  def classes_hash
-    @classes
-  end
+    def current_section
+      if section = @temporary_section
+        @temporary_section = nil
+      else
+        section = @current_section
+      end
 
-  ##
-  # The current documentation section that new items will be added to.  If
-  # temporary_section is available it will be used.
+      section
+    end
 
-  def current_section
-    if section = @temporary_section then
-      @temporary_section = nil
-    else
-      section = @current_section
+    def display(method_attr) # :nodoc:
+      if method_attr.is_a? Attr
+        "#{method_attr.definition} #{method_attr.pretty_name}"
+      else
+        "method #{method_attr.pretty_name}"
+      end
     end
 
-    section
-  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 display(method_attr) # :nodoc:
-    if method_attr.is_a? RDoc::Attr
-      "#{method_attr.definition} #{method_attr.pretty_name}"
-    else
-      "method #{method_attr.pretty_name}"
+    def each_ancestor(&_) # :nodoc:
     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.
+    ##
+    # Iterator for classes and modules
 
-  def each_ancestor(&_) # :nodoc:
-  end
+    def each_classmodule(&block) # :yields: module
+      classes_and_modules.sort.each(&block)
+    end
 
-  ##
-  # Iterator for classes and modules
+    ##
+    # Iterator for methods
 
-  def each_classmodule(&block) # :yields: module
-    classes_and_modules.sort.each(&block)
-  end
+    def each_method # :yields: method
+      return enum_for __method__ unless block_given?
 
-  ##
-  # Iterator for methods
+      @method_list.sort.each { |m| yield m }
+    end
 
-  def each_method # :yields: method
-    return enum_for __method__ unless block_given?
+    ##
+    # 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
 
-    @method_list.sort.each { |m| yield m }
-  end
+    def each_section # :yields: section, constants, attributes
+      return enum_for __method__ unless block_given?
 
-  ##
-  # 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
+      constants  = @constants.group_by  do |constant|  constant.section end
+      attributes = @attributes.group_by do |attribute| attribute.section end
 
-  def each_section # :yields: section, constants, attributes
-    return enum_for __method__ unless block_given?
+      constants.default  = []
+      attributes.default = []
 
-    constants  = @constants.group_by  do |constant|  constant.section end
-    attributes = @attributes.group_by do |attribute| attribute.section end
+      sort_sections.each do |section|
+        yield section, constants[section].select(&:display?).sort, attributes[section].select(&:display?).sort
+      end
+    end
 
-    constants.default  = []
-    attributes.default = []
+    ##
+    # Finds an attribute +name+ with singleton value +singleton+.
 
-    sort_sections.each do |section|
-      yield section, constants[section].select(&:display?).sort, attributes[section].select(&:display?).sort
+    def find_attribute(name, singleton)
+      name = $1 if name =~ /^(.*)=$/
+      @attributes.find { |a| a.name == name && a.singleton == singleton }
     end
-  end
 
-  ##
-  # Finds an attribute +name+ with singleton value +singleton+.
+    ##
+    # Finds an attribute with +name+ in this context
 
-  def find_attribute(name, singleton)
-    name = $1 if name =~ /^(.*)=$/
-    @attributes.find { |a| a.name == name && a.singleton == singleton }
-  end
+    def find_attribute_named(name)
+      case name
+      when /\A#/
+        find_attribute name[1..-1], false
+      when /\A::/
+        find_attribute name[2..-1], true
+      else
+        @attributes.find { |a| a.name == name }
+      end
+    end
 
-  ##
-  # Finds an attribute with +name+ in this context
+    ##
+    # Finds a class method 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 }
+    def find_class_method_named(name)
+      @method_list.find { |meth| meth.singleton && meth.name == name }
     end
-  end
 
-  ##
-  # Finds a class method with +name+ in this context
+    ##
+    # Finds a constant with +name+ in this context
 
-  def find_class_method_named(name)
-    @method_list.find { |meth| meth.singleton && meth.name == name }
-  end
+    def find_constant_named(name)
+      @constants.find do |m|
+        m.name == name || m.full_name == name
+      end
+    end
 
-  ##
-  # Finds a constant with +name+ in this context
+    ##
+    # Tries to find a module at a higher scope.
+    # But parent is not always a higher module nesting scope, so the result is not correct.
+    # Parent chain can only represent last-opened nesting, and may be broken in some cases.
+    # The Ruby parser does not represent module nesting with the parent chain.
 
-  def find_constant_named(name)
-    @constants.find do |m|
-      m.name == name || m.full_name == name
+    def find_enclosing_module_named(name)
+      parent && parent.find_module_named(name)
     end
-  end
 
-  ##
-  # Tries to find a module at a higher scope.
-  # But parent is not always a higher module nesting scope, so the result is not correct.
-  # Parent chain can only represent last-opened nesting, and may be broken in some cases.
-  # PrismRuby parser stopped representing module nesting with parent chain at all.
+    ##
+    # Finds an external alias +name+ with singleton value +singleton+.
 
-  def find_enclosing_module_named(name)
-    parent && parent.find_module_named(name)
-  end
+    def find_external_alias(name, singleton)
+      @external_aliases.find { |m| m.name == name && m.singleton == singleton }
+    end
 
-  ##
-  # Finds an external alias +name+ with singleton value +singleton+.
+    ##
+    # Finds an external alias with +name+ in this context
 
-  def find_external_alias(name, singleton)
-    @external_aliases.find { |m| m.name == name && m.singleton == singleton }
-  end
+    def find_external_alias_named(name)
+      case name
+      when /\A#/
+        find_external_alias name[1..-1], false
+      when /\A::/
+        find_external_alias name[2..-1], true
+      else
+        @external_aliases.find { |a| a.name == name }
+      end
+    end
 
-  ##
-  # Finds an external alias with +name+ in this context
+    ##
+    # Finds an instance method 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 }
+    def find_instance_method_named(name)
+      @method_list.find { |meth| !meth.singleton && meth.name == name }
     end
-  end
 
-  ##
-  # Finds an instance method with +name+ in this context
+    ##
+    # 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
+      @store.find_file_named(symbol)
+    end
 
-  def find_instance_method_named(name)
-    @method_list.find { |meth| !meth.singleton && meth.name == name }
-  end
+    ##
+    # Finds a method named +name+ with singleton value +singleton+.
 
-  ##
-  # 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
-    @store.find_file_named(symbol)
-  end
+    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 method named +name+ with singleton value +singleton+.
+    ##
+    # Finds a instance or module method with +name+ in this context
 
-  def find_method(name, singleton)
-    @method_list.find { |m|
-      if m.singleton
-        m.name == name && m.singleton == singleton
+    def find_method_named(name)
+      case name
+      when /\A#/
+        find_method name[1..-1], false
+      when /\A::/
+        find_method name[2..-1], true
       else
-        m.name == name && !m.singleton && !singleton
+        @method_list.find { |meth| meth.name == name }
       end
-    }
-  end
+    end
 
-  ##
-  # Finds a instance or module method with +name+ in this context
+    ##
+    # Find a module with +name+ trying to using ruby's scoping rules.
+    # find_enclosing_module_named cannot use ruby's scoping so the result is not correct.
 
-  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 }
+    def find_module_named(name)
+      res = get_module_named(name)
+      return res if res
+      return self if self.name == name
+      find_enclosing_module_named name
     end
-  end
 
-  ##
-  # Find a module with +name+ trying to using ruby's scoping rules.
-  # find_enclosing_module_named cannot use ruby's scoping so the result is not correct.
-
-  def find_module_named(name)
-    res = get_module_named(name)
-    return res if res
-    return self if self.name == name
-    find_enclosing_module_named name
-  end
+    # Get a module named +name+ in this context
+    # Don't look up for higher module nesting scopes. RDoc::Context doesn't have that information.
 
-  # Get a module named +name+ in this context
-  # Don't look up for higher module nesting scopes. RDoc::Context doesn't have that information.
-
-  def get_module_named(name)
-    @modules[name] || @classes[name]
-  end
+    def get_module_named(name)
+      @modules[name] || @classes[name]
+    end
 
-  ##
-  # Look up +symbol+, first as a module, then as a local symbol.
+    ##
+    # 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
+    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
+    ##
+    # Look up a module named +symbol+.
+
+    def find_symbol_module(symbol)
+      result = nil
+
+      # look for a class or module 'symbol'
+      case symbol
+      when /^::/
+        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?(TopLevel)
+          searched = searched.parent
+        end
+      else
+        searched = self
+        while searched do
+          result = searched.find_module_named(symbol)
+          break if result || searched.is_a?(TopLevel)
+          searched = searched.parent
+        end
       end
+
+      result
     end
 
-    result
-  end
+    ##
+    # The full name for this context.  This method is overridden by subclasses.
 
-  ##
-  # The full name for this context.  This method is overridden by subclasses.
+    def full_name
+      '(unknown)'
+    end
 
-  def full_name
-    '(unknown)'
-  end
+    ##
+    # Does this context and its methods and constants all have documentation?
+    #
+    # (Yes, fully documented doesn't mean everything.)
 
-  ##
-  # 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
+    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+
+    ##
+    # URL for this with a +prefix+
 
-  def http_url
-    path = name_for_path
-    path = path.gsub(/<<\s*(\w*)/, 'from-\1') if path =~ /<</
-    path = path.split('::')
+    def http_url
+      path = name_for_path
+      path = path.gsub(/<<\s*(\w*)/, 'from-\1') if path =~ /<</
+      path = path.split('::')
 
-    File.join(*path.compact) + '.html'
-  end
+      File.join(*path.compact) + '.html'
+    end
 
-  ##
-  # Instance attributes
+    ##
+    # Instance methods
 
-  def instance_attributes
-    @instance_attributes ||= attributes.reject { |a| a.singleton }
-  end
+    def instance_methods
+      method_list.reject { |a| a.singleton }
+    end
 
-  ##
-  # Instance methods
+    ##
+    # 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 instance_methods
-    @instance_methods ||= method_list.reject { |a| a.singleton }
-  end
+    def methods_by_type(section = nil)
+      methods = {}
 
-  ##
-  # Instance methods
-  #--
-  # TODO remove this later
+      TYPES.each do |type|
+        visibilities = {}
+        VISIBILITIES.each do |vis|
+          visibilities[vis] = []
+        end
 
-  def instance_method_list
-    warn '#instance_method_list is obsoleted, please use #instance_methods'
-    @instance_methods ||= method_list.reject { |a| a.singleton }
-  end
+        methods[type] = visibilities
+      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] = []
+      each_method do |method|
+        next if section and not method.section == section
+        methods[method.type][method.visibility] << method
       end
 
-      methods[type] = visibilities
+      methods
     end
 
-    each_method do |method|
-      next if section and not method.section == section
-      methods[method.type][method.visibility] << method
-    end
+    ##
+    # Yields AnyMethod and Attr entries matching the list of names in +methods+.
 
-    methods
-  end
+    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
 
-  ##
-  # Yields AnyMethod and Attr entries matching the list of names in +methods+.
+      each_ancestor do |parent|
+        parent.methods_matching(methods, singleton, &block)
+      end
+    end
+
+    ##
+    # Array of modules in this context
 
-  def methods_matching(methods, singleton = false, &block)
-    (@method_list + @attributes).each do |m|
-      yield m if methods.include?(m.name) and m.singleton == singleton
+    def modules
+      @modules.values
     end
 
-    each_ancestor do |parent|
-      parent.methods_matching(methods, singleton, &block)
+    ##
+    # Hash of modules keyed by module name
+
+    def modules_hash
+      @modules
     end
-  end
 
-  ##
-  # Array of modules in this context
+    ##
+    # Name to use to generate the url.
+    # <tt>#full_name</tt> by default.
 
-  def modules
-    @modules.values
-  end
+    def name_for_path
+      full_name
+    end
 
-  ##
-  # Hash of modules keyed by module name
+    ##
+    # Record +top_level+ as a file +self+ is in.
 
-  def modules_hash
-    @modules
-  end
+    def record_location(top_level)
+      @in_files << top_level unless @in_files.include?(top_level)
+    end
 
-  ##
-  # Name to use to generate the url.
-  # <tt>#full_name</tt> by default.
+    ##
+    # 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?
+      # Contexts that are still ignored here were created inside a :stopdoc:
+      # region and never received documentable contents afterwards
+      @remove_from_documentation ||=
+        (@received_nodoc || @ignored) &&
+        !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
 
-  def name_for_path
-    full_name
-  end
+    ##
+    # Removes methods and attributes with a visibility less than +min_visibility+.
+    #--
+    # TODO mark the visibility of attributes in the template (if not public?)
 
-  ##
-  # Changes the visibility for new methods to +visibility+
+    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 ongoing_visibility=(visibility)
-    @visibility = visibility
-  end
+    ##
+    # Only called when min_visibility == :public or :private
 
-  ##
-  # Record +top_level+ as a file +self+ is in.
+    def remove_invisible_in(array, min_visibility) # :nodoc:
+      if min_visibility == :public
+        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
 
-  def record_location(top_level)
-    @in_files << top_level unless @in_files.include?(top_level)
-  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
 
-  ##
-  # 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
+    ##
+    # Returns RDoc::Context::Section objects referenced in this context for use
+    # in a table of contents.
 
-  ##
-  # 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
+    def section_contents
+      used_sections = {}
 
-  ##
-  # Only called when min_visibility == :public or :private
+      each_method do |method|
+        next unless method.display?
 
-  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
+        used_sections[method.section] = true
+      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
+      # order found sections
+      sections = sort_sections.select do |section|
+        used_sections[section]
+      end
 
-  ##
-  # Returns RDoc::Context::Section objects referenced in this context for use
-  # in a table of contents.
+      # only the default section is used
+      return [] if
+        sections.length == 1 and not sections.first.title
 
-  def section_contents
-    used_sections = {}
+      sections
+    end
 
-    each_method do |method|
-      next unless method.display?
+    ##
+    # Sections in this context
 
-      used_sections[method.section] = true
+    def sections
+      @sections.values
     end
 
-    # order found sections
-    sections = sort_sections.select do |section|
-      used_sections[section]
+    def sections_hash # :nodoc:
+      @sections
     end
 
-    # only the default section is used
-    return [] if
-      sections.length == 1 and not sections.first.title
+    ##
+    # Sets the current section to a section with +title+.  See also #add_section
 
-    sections
-  end
+    def set_current_section(title, comment)
+      @current_section = add_section title, comment
+    end
 
-  ##
-  # Sections in this context
+    ##
+    # Given an array +methods+ of method names, set the visibility of each to
+    # +visibility+
 
-  def sections
-    @sections.values
-  end
+    def set_visibility_for(methods, visibility, singleton = false)
+      methods_matching methods, singleton do |m|
+        m.visibility = visibility
+      end
+    end
 
-  def sections_hash # :nodoc:
-    @sections
-  end
+    ##
+    # Given an array +names+ of constants, set the visibility of each constant to
+    # +visibility+
 
-  ##
-  # Sets the current section to a section with +title+.  See also #add_section
+    def set_constant_visibility_for(names, visibility)
+      names.each do |name|
+        constant = @constants_hash[name] or next
+        constant.visibility = visibility
+      end
+    end
 
-  def set_current_section(title, comment)
-    @current_section = add_section title, comment
-  end
+    ##
+    # Sorts sections alphabetically (default) or in TomDoc fashion (none,
+    # Public, Internal, Deprecated)
 
-  ##
-  # Given an array +methods+ of method names, set the visibility of each to
-  # +visibility+
+    def sort_sections
+      titles = @sections.map { |title, _| title }
 
-  def set_visibility_for(methods, visibility, singleton = false)
-    methods_matching methods, singleton do |m|
-      m.visibility = visibility
+      if titles.length > 1 and
+         TOMDOC_TITLES_SORT ==
+           (titles | TOMDOC_TITLES).sort_by { |title| title.to_s }
+        @sections.values_at(*TOMDOC_TITLES).compact
+      else
+        @sections.sort_by { |title, _|
+          title.to_s
+        }.map { |_, section|
+          section
+        }
+      end
     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
+    def to_s # :nodoc:
+      "#{self.class.name} #{self.full_name}"
     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
-      }
+    ##
+    # 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 TopLevel === @top_level
+      @top_level
     end
-  end
 
-  def to_s # :nodoc:
-    "#{self.class.name} #{self.full_name}"
-  end
+    ##
+    # Upgrades NormalModule +mod+ in +enclosing+ to a +class_type+
 
-  ##
-  # 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
+    def upgrade_to_class(mod, class_type, enclosing)
+      enclosing.modules_hash.delete mod.name
 
-  ##
-  # Upgrades NormalModule +mod+ in +enclosing+ to a +class_type+
+      klass = ClassModule.from_module class_type, mod
+      klass.store = @store
 
-  def upgrade_to_class(mod, class_type, enclosing)
-    enclosing.modules_hash.delete mod.name
+      # 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 = RDoc::ClassModule.from_module class_type, mod
-    klass.store = @store
+      klass
+    end
 
-    # 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
+    autoload :Section, "#{__dir__}/context/section"
 
-    klass
   end
-
-  autoload :Section, "#{__dir__}/context/section"
-
 end