rdoc 6.17.0 → 8.1.0

data/lib/rdoc/code_object/class_module.rb

@@ -1,888 +1,975 @@
 # frozen_string_literal: true
-##
-# ClassModule is the base class for objects representing either a class or a
-# module.
+module RDoc
+  ##
+  # ClassModule is the base class for objects representing either a class or a
+  # module.
+
+  class ClassModule < ::RDoc::Context
+
+    ##
+    # 1::
+    #   RDoc 3.7
+    #   * Added visibility, singleton and file to attributes
+    #   * Added file to constants
+    #   * Added file to includes
+    #   * Added file to methods
+    # 2::
+    #   RDoc 3.13
+    #   * Added extends
+    # 3::
+    #   RDoc 4.0
+    #   * Added sections
+    #   * Added in_files
+    #   * Added parent name
+    #   * Complete Constant dump
+
+    MARSHAL_VERSION = 3 # :nodoc:
+
+    ##
+    # Constants that are aliases for this class or module
+
+    attr_accessor :constant_aliases
+
+    ##
+    # A hash of <tt>{ location => [comments] }</tt> documenting this class/module.
+    # Use #add_comment to add comments.
+    #
+    # Ruby hashes maintain insertion order, so comments render in the order
+    # they were first added. Each location maps to an array of comments,
+    # allowing a class reopened in the same file to accumulate multiple comments.
+    #
+    # Before marshalling:
+    # - +location+ is an RDoc::TopLevel
+    # - +comments+ are Strings
+    #
+    # After unmarshalling:
+    # - +location+ is a filename String
+    # - +comments+ are RDoc::Markup::Documents
+
+    attr_accessor :comment_location
+
+    ##
+    # Class or module this constant is an alias for
+
+    attr_accessor :is_alias_for
+
+    ##
+    # Return a RDoc::ClassModule of class +class_type+ that is a copy
+    # of module +module+. Used to promote modules to classes.
+    #--
+    # TODO move to RDoc::NormalClass (I think)
+
+    def self.from_module(class_type, mod)
+      klass = class_type.new mod.name
+
+      mod.comment_location.each do |location, comments|
+        comments.each { |comment| klass.add_comment comment, location }
+      end
 
-class RDoc::ClassModule < RDoc::Context
+      klass.parent = mod.parent
+      klass.section = mod.section
+
+      klass.attributes.concat mod.attributes
+      klass.method_list.concat mod.method_list
+      klass.aliases.concat mod.aliases
+      klass.external_aliases.concat mod.external_aliases
+      klass.constants.concat mod.constants
+      klass.includes.concat mod.includes
+      klass.extends.concat mod.extends
+
+      klass.methods_hash.update mod.methods_hash
+      klass.constants_hash.update mod.constants_hash
+
+      klass.current_section = mod.current_section
+      klass.in_files.concat mod.in_files
+      klass.sections.concat mod.sections
+      klass.unmatched_alias_lists = mod.unmatched_alias_lists
+      klass.current_section = mod.current_section
+      klass.classes_hash.update mod.classes_hash
+      klass.modules_hash.update mod.modules_hash
+      klass.metadata.update mod.metadata
+
+      klass.document_self = mod.received_nodoc ? nil : mod.document_self
+      klass.document_children = mod.document_children
+      klass.force_documentation = mod.force_documentation
+      klass.done_documenting = mod.done_documenting
+
+      # update the parent of all children
+
+      (klass.attributes +
+       klass.method_list +
+       klass.aliases +
+       klass.external_aliases +
+       klass.constants +
+       klass.includes +
+       klass.extends +
+       klass.classes +
+       klass.modules).each do |obj|
+        obj.parent = klass
+        obj.full_name = nil
+      end
 
-  ##
-  # 1::
-  #   RDoc 3.7
-  #   * Added visibility, singleton and file to attributes
-  #   * Added file to constants
-  #   * Added file to includes
-  #   * Added file to methods
-  # 2::
-  #   RDoc 3.13
-  #   * Added extends
-  # 3::
-  #   RDoc 4.0
-  #   * Added sections
-  #   * Added in_files
-  #   * Added parent name
-  #   * Complete Constant dump
-
-  MARSHAL_VERSION = 3 # :nodoc:
+      klass
+    end
 
-  ##
-  # Constants that are aliases for this class or module
+    ##
+    # Creates a new ClassModule with +name+ with optional +superclass+
+    #
+    # This is a constructor for subclasses, and must never be called directly.
 
-  attr_accessor :constant_aliases
+    def initialize(name, superclass = nil)
+      @constant_aliases = []
+      @is_alias_for     = nil
+      @name             = name
+      @superclass       = superclass
+      @comment_location = {} # Hash of { location => [comments] }
 
-  ##
-  # Comment and the location it came from.  Use #add_comment to add comments
+      super()
+    end
 
-  attr_accessor :comment_location
+    ##
+    # Adds +comment+ to this ClassModule's list of comments at +location+.  This
+    # method is preferred over #comment= since it allows ri data to be updated
+    # across multiple runs.
 
-  ##
-  # Class or module this constant is an alias for
+    def add_comment(comment, location)
+      return unless document_self
 
-  attr_accessor :is_alias_for
+      original = comment
 
-  ##
-  # Return a RDoc::ClassModule of class +class_type+ that is a copy
-  # of module +module+. Used to promote modules to classes.
-  #--
-  # TODO move to RDoc::NormalClass (I think)
-
-  def self.from_module(class_type, mod)
-    klass = class_type.new mod.name
-
-    mod.comment_location.each do |comment, location|
-      klass.add_comment comment, location
-    end
-
-    klass.parent = mod.parent
-    klass.section = mod.section
-
-    klass.attributes.concat mod.attributes
-    klass.method_list.concat mod.method_list
-    klass.aliases.concat mod.aliases
-    klass.external_aliases.concat mod.external_aliases
-    klass.constants.concat mod.constants
-    klass.includes.concat mod.includes
-    klass.extends.concat mod.extends
-
-    klass.methods_hash.update mod.methods_hash
-    klass.constants_hash.update mod.constants_hash
-
-    klass.current_section = mod.current_section
-    klass.in_files.concat mod.in_files
-    klass.sections.concat mod.sections
-    klass.unmatched_alias_lists = mod.unmatched_alias_lists
-    klass.current_section = mod.current_section
-    klass.visibility = mod.visibility
-
-    klass.classes_hash.update mod.classes_hash
-    klass.modules_hash.update mod.modules_hash
-    klass.metadata.update mod.metadata
-
-    klass.document_self = mod.received_nodoc ? nil : mod.document_self
-    klass.document_children = mod.document_children
-    klass.force_documentation = mod.force_documentation
-    klass.done_documenting = mod.done_documenting
-
-    # update the parent of all children
-
-    (klass.attributes +
-     klass.method_list +
-     klass.aliases +
-     klass.external_aliases +
-     klass.constants +
-     klass.includes +
-     klass.extends +
-     klass.classes +
-     klass.modules).each do |obj|
-      obj.parent = klass
-      obj.full_name = nil
-    end
-
-    klass
-  end
+      comment = case comment
+                when Comment
+                  comment.normalize
+                else
+                  normalize_comment comment
+                end
 
-  ##
-  # Creates a new ClassModule with +name+ with optional +superclass+
-  #
-  # This is a constructor for subclasses, and must never be called directly.
-
-  def initialize(name, superclass = nil)
-    @constant_aliases = []
-    @is_alias_for     = nil
-    @name             = name
-    @superclass       = superclass
-    @comment_location = [] # [[comment, location]]
-
-    super()
-  end
+      (@comment_location[location] ||= []) << comment
 
-  ##
-  # Adds +comment+ to this ClassModule's list of comments at +location+.  This
-  # method is preferred over #comment= since it allows ri data to be updated
-  # across multiple runs.
+      self.comment = original
+    end
 
-  def add_comment(comment, location)
-    return unless document_self
+    def add_things(my_things, other_things) # :nodoc:
+      other_things.each do |group, things|
+        my_things[group].each { |thing| yield false, thing } if
+          my_things.include? group
 
-    original = comment
+        things.each do |thing|
+          yield true, thing
+        end
+      end
+    end
 
-    comment = case comment
-              when RDoc::Comment then
-                comment.normalize
-              else
-                normalize_comment comment
-              end
+    ##
+    # Ancestors list for this ClassModule: the list of included modules
+    # (classes will add their superclass if any).
+    #
+    # Returns the included classes or modules, not the includes
+    # themselves. The returned values are either String or
+    # RDoc::NormalModule instances (see RDoc::Include#module).
+    #
+    # The values are returned in reverse order of their inclusion,
+    # which is the order suitable for searching methods/attributes
+    # in the ancestors. The superclass, if any, comes last.
 
-    if location.parser == RDoc::Parser::C
-      @comment_location.delete_if { |(_, l)| l == location }
+    def ancestors
+      included_ancestors
     end
 
-    @comment_location << [comment, location]
+    def included_ancestors # :nodoc:
+      includes.map { |i| i.module }.reverse
+    end
 
-    self.comment = original
-  end
+    def aref_prefix # :nodoc:
+      raise NotImplementedError, "missing aref_prefix for #{self.class}"
+    end
 
-  def add_things(my_things, other_things) # :nodoc:
-    other_things.each do |group, things|
-      my_things[group].each { |thing| yield false, thing } if
-        my_things.include? group
+    ##
+    # HTML fragment reference for this module or class using GitHub-style
+    # anchor format (lowercase, :: replaced with -).
+    #
+    # Examples:
+    #   Foo      -> class-foo
+    #   Foo::Bar -> class-foo-bar
 
-      things.each do |thing|
-        yield true, thing
-      end
+    def aref
+      "#{aref_prefix}-#{full_name.downcase.gsub('::', '-')}"
     end
-  end
 
-  ##
-  # Ancestors list for this ClassModule: the list of included modules
-  # (classes will add their superclass if any).
-  #
-  # Returns the included classes or modules, not the includes
-  # themselves. The returned values are either String or
-  # RDoc::NormalModule instances (see RDoc::Include#module).
-  #
-  # The values are returned in reverse order of their inclusion,
-  # which is the order suitable for searching methods/attributes
-  # in the ancestors. The superclass, if any, comes last.
-
-  def ancestors
-    includes.map { |i| i.module }.reverse
-  end
+    ##
+    # Legacy HTML fragment reference for backward compatibility.
+    # Returns the old RDoc-style anchor format.
+    #
+    # Examples:
+    #   Foo      -> class-Foo
+    #   Foo::Bar -> class-Foo::Bar
 
-  def aref_prefix # :nodoc:
-    raise NotImplementedError, "missing aref_prefix for #{self.class}"
-  end
+    def legacy_aref
+      "#{aref_prefix}-#{full_name}"
+    end
 
-  ##
-  # HTML fragment reference for this module or class.  See
-  # RDoc::NormalClass#aref and RDoc::NormalModule#aref
+    ##
+    # Ancestors of this class or module only
 
-  def aref
-    "#{aref_prefix}-#{full_name}"
-  end
+    alias direct_ancestors ancestors
 
-  ##
-  # Ancestors of this class or module only
+    ##
+    # Clears the comment. Used by the Ruby parser.
 
-  alias direct_ancestors ancestors
+    def clear_comment
+      @comment = ''
+    end
 
-  ##
-  # Clears the comment. Used by the Ruby parser.
+    ##
+    # This method is deprecated, use #add_comment instead.
+    #
+    # Appends +comment+ to the current comment, but separated by a rule.  Works
+    # more like <tt>+=</tt>.
 
-  def clear_comment
-    @comment = ''
-  end
+    def comment=(comment) # :nodoc:
+      comment = case comment
+                when Comment
+                  comment.normalize
+                else
+                  normalize_comment comment
+                end
 
-  ##
-  # This method is deprecated, use #add_comment instead.
-  #
-  # Appends +comment+ to the current comment, but separated by a rule.  Works
-  # more like <tt>+=</tt>.
-
-  def comment=(comment) # :nodoc:
-    comment = case comment
-              when RDoc::Comment then
-                comment.normalize
-              else
-                normalize_comment comment
-              end
+      comment = "#{@comment.to_s}\n---\n#{comment.to_s}" unless @comment.empty?
 
-    comment = "#{@comment.to_s}\n---\n#{comment.to_s}" unless @comment.empty?
+      super comment
+    end
 
-    super comment
-  end
+    ##
+    # Prepares this ClassModule for use by a generator.
+    #
+    # See RDoc::Store#complete
 
-  ##
-  # Prepares this ClassModule for use by a generator.
-  #
-  # See RDoc::Store#complete
-
-  def complete(min_visibility)
-    update_aliases
-    remove_nodoc_children
-    embed_mixins
-    update_includes
-    update_extends
-    remove_invisible min_visibility
-  end
+    def complete(min_visibility)
+      update_aliases
+      remove_nodoc_children
+      embed_mixins
+      update_includes
+      update_extends
+      remove_invisible min_visibility
+    end
 
-  ##
-  # Does this ClassModule or any of its methods have document_self set?
+    ##
+    # Does this ClassModule or any of its methods have document_self set?
 
-  def document_self_or_methods
-    document_self || method_list.any?{ |m| m.document_self }
-  end
+    def document_self_or_methods
+      document_self || method_list.any?{ |m| m.document_self }
+    end
 
-  ##
-  # Does this class or module have a comment with content or is
-  # #received_nodoc true?
+    ##
+    # Does this class or module have a comment with content or is
+    # #received_nodoc true?
 
-  def documented?
-    return true if @received_nodoc
-    return false if @comment_location.empty?
-    @comment_location.any? { |comment, _| not comment.empty? }
-  end
+    def documented?
+      return true if @received_nodoc
+      return false if @comment_location.empty?
+      @comment_location.each_value.any? { |comments| comments.any? { |c| not c.empty? } }
+    end
 
-  ##
-  # Iterates the ancestors of this class or module for which an
-  # RDoc::ClassModule exists.
+    ##
+    # Iterates the ancestors of this class or module for which an
+    # RDoc::ClassModule exists.
 
-  def each_ancestor # :yields: module
-    return enum_for __method__ unless block_given?
+    def each_ancestor # :yields: module
+      return enum_for __method__ unless block_given?
 
-    ancestors.each do |mod|
-      next if String === mod
-      next if self == mod
-      yield mod
+      ancestors.each do |mod|
+        next if String === mod
+        next if self == mod
+        yield mod
+      end
     end
-  end
 
-  ##
-  # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
+    ##
+    # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
 
-  def find_ancestor_local_symbol(symbol)
-    each_ancestor do |m|
-      res = m.find_local_symbol(symbol)
-      return res if res
-    end
+    def find_ancestor_local_symbol(symbol)
+      each_ancestor do |m|
+        res = m.find_local_symbol(symbol)
+        return res if res
+      end
 
-    nil
-  end
+      nil
+    end
 
-  ##
-  # Finds a class or module with +name+ in this namespace or its descendants
+    ##
+    # Finds a class or module with +name+ in this namespace or its descendants
 
-  def find_class_named(name)
-    return self if full_name == name
-    return self if @name == name
+    def find_class_named(name)
+      return self if full_name == name
+      return self if @name == name
 
-    @classes.values.find do |klass|
-      next if klass == self
-      klass.find_class_named name
+      @classes.values.find do |klass|
+        next if klass == self
+        klass.find_class_named name
+      end
     end
-  end
 
-  ##
-  # Return the fully qualified name of this class or module
-
-  def full_name
-    @full_name ||= if RDoc::ClassModule === parent then
-                     "#{parent.full_name}::#{@name}"
-                   else
-                     @name
-                   end
-  end
+    ##
+    # Return the fully qualified name of this class or module
 
-  ##
-  # Return array of full_name splitted by +::+.
+    def full_name
+      @full_name ||= if ClassModule === parent
+                       "#{parent.full_name}::#{@name}"
+                     else
+                       @name
+                     end
+    end
 
-  def nesting_namespaces
-    @namespaces ||= full_name.split("::").reject(&:empty?)
-  end
+    ##
+    # Return array of full_name splitted by +::+.
 
-  ##
-  # Return array of fully qualified nesting namespaces.
-  #
-  # For example, if full_name is +A::B::C+, this method returns <code>["A", "A::B", "A::B::C"]</code>
+    def nesting_namespaces
+      @namespaces ||= full_name.split("::").reject(&:empty?)
+    end
+
+    ##
+    # Return array of fully qualified nesting namespaces.
+    #
+    # For example, if full_name is +A::B::C+, this method returns <code>["A", "A::B", "A::B::C"]</code>
 
-  def fully_qualified_nesting_namespaces
-    return nesting_namespaces if nesting_namespaces.length < 2
-    @fqns ||= nesting_namespaces.inject([]) do |list, n|
-      list << (list.empty? ? n : "#{list.last}::#{n}")
+    def fully_qualified_nesting_namespaces
+      return nesting_namespaces if nesting_namespaces.length < 2
+      @fqns ||= nesting_namespaces.inject([]) do |list, n|
+        list << (list.empty? ? n : "#{list.last}::#{n}")
+      end
     end
-  end
 
-  ##
-  # TODO: filter included items by #display?
+    ##
+    # TODO: filter included items by #display?
 
-  def marshal_dump # :nodoc:
-    attrs = attributes.sort.map do |attr|
-      next unless attr.display?
-      [ attr.name, attr.rw,
-        attr.visibility, attr.singleton, attr.file_name,
-      ]
-    end.compact
-
-    method_types = methods_by_type.map do |type, visibilities|
-      visibilities = visibilities.map do |visibility, methods|
-        method_names = methods.map do |method|
-          next unless method.display?
-          [method.name, method.file_name]
-        end.compact
-
-        [visibility, method_names.uniq]
-      end
-
-      [type, visibilities]
-    end
-
-    [ MARSHAL_VERSION,
-      @name,
-      full_name,
-      @superclass,
-      parse(@comment_location),
-      attrs,
-      constants.select { |constant| constant.display? },
-      includes.map do |incl|
-        next unless incl.display?
-        [incl.name, parse(incl.comment), incl.file_name]
-      end.compact,
-      method_types,
-      extends.map do |ext|
-        next unless ext.display?
-        [ext.name, parse(ext.comment), ext.file_name]
-      end.compact,
-      @sections.values,
-      @in_files.map do |tl|
-        tl.relative_name
-      end,
-      parent.full_name,
-      parent.class,
-    ]
-  end
+    def marshal_dump # :nodoc:
+      attrs = attributes.sort.map do |attr|
+        next unless attr.display?
+        [ attr.name, attr.rw,
+          attr.visibility, attr.singleton, attr.file_name,
+        ]
+      end.compact
 
-  def marshal_load(array) # :nodoc:
-    initialize_visibility
-    initialize_methods_etc
-    @current_section   = nil
-    @document_self     = true
-    @done_documenting  = false
-    @parent            = nil
-    @temporary_section = nil
-    @visibility        = nil
-    @classes           = {}
-    @modules           = {}
-
-    @name       = array[1]
-    @full_name  = array[2]
-    @superclass = array[3]
-    document    = array[4]
-
-    @comment    = RDoc::Comment.from_document document
-
-    @comment_location = if RDoc::Markup::Document === document.parts.first then
-                          document
-                        else
-                          RDoc::Markup::Document.new document
-                        end
-
-    array[5].each do |name, rw, visibility, singleton, file|
-      singleton  ||= false
-      visibility ||= :public
-
-      attr = RDoc::Attr.new nil, name, rw, nil, singleton: singleton
-
-      add_attribute attr
-      attr.visibility = visibility
-      attr.record_location RDoc::TopLevel.new file
-    end
-
-    array[6].each do |constant, document, file|
-      case constant
-      when RDoc::Constant then
-        add_constant constant
-      else
-        constant = add_constant RDoc::Constant.new(constant, nil, RDoc::Comment.from_document(document))
-        constant.record_location RDoc::TopLevel.new file
+      method_types = methods_by_type.map do |type, visibilities|
+        visibilities = visibilities.map do |visibility, methods|
+          method_names = methods.map do |method|
+            next unless method.display?
+            [method.name, method.file_name]
+          end.compact
+
+          [visibility, method_names.uniq]
+        end
+
+        [type, visibilities]
       end
-    end
 
-    array[7].each do |name, document, file|
-      incl = add_include RDoc::Include.new(name, RDoc::Comment.from_document(document))
-      incl.record_location RDoc::TopLevel.new file
+      [ MARSHAL_VERSION,
+        @name,
+        full_name,
+        @superclass,
+        parse(@comment_location),
+        attrs,
+        constants.select { |constant| constant.display? },
+        includes.map do |incl|
+          next unless incl.display?
+          [incl.name, parse(incl.comment), incl.file_name]
+        end.compact,
+        method_types,
+        extends.map do |ext|
+          next unless ext.display?
+          [ext.name, parse(ext.comment), ext.file_name]
+        end.compact,
+        @sections.values,
+        @in_files.map do |tl|
+          tl.relative_name
+        end,
+        parent.full_name,
+        parent.class,
+      ]
     end
 
-    array[8].each do |type, visibilities|
-      visibilities.each do |visibility, methods|
-        @visibility = visibility
+    def marshal_load(array) # :nodoc:
+      initialize_visibility
+      initialize_methods_etc
+      @current_section   = nil
+      @document_self     = true
+      @done_documenting  = false
+      @parent            = nil
+      @temporary_section = nil
+      @classes           = {}
+      @modules           = {}
+
+      @name       = array[1]
+      @full_name  = array[2]
+      @superclass = array[3]
+      document    = array[4]
+
+      @comment    = Comment.from_document document
+
+      @comment_location = if document.parts.first.is_a?(Markup::Document)
+                            document.parts.group_by(&:file)
+                          else
+                            { document.file => [document] }
+                          end
 
-        methods.each do |name, file|
-          method = RDoc::AnyMethod.new nil, name, singleton: type == 'class'
-          method.record_location RDoc::TopLevel.new file
-          add_method method
+      array[5].each do |name, rw, visibility, singleton, file|
+        singleton  ||= false
+        visibility ||= :public
+
+        attr = Attr.new name, rw, nil, singleton: singleton
+
+        add_attribute attr
+        attr.visibility = visibility
+        attr.record_location TopLevel.new file
+      end
+
+      array[6].each do |constant, document, file|
+        case constant
+        when Constant
+          add_constant constant
+        else
+          constant = add_constant Constant.new(constant, nil, Comment.from_document(document))
+          constant.record_location TopLevel.new file
         end
       end
-    end
 
-    array[9].each do |name, document, file|
-      ext = add_extend RDoc::Extend.new(name, RDoc::Comment.from_document(document))
-      ext.record_location RDoc::TopLevel.new file
-    end if array[9] # Support Marshal version 1
+      array[7].each do |name, document, file|
+        incl = add_include Include.new(name, Comment.from_document(document))
+        incl.record_location TopLevel.new file
+      end
+
+      array[8].each do |type, visibilities|
+        visibilities.each do |visibility, methods|
+          methods.each do |name, file|
+            method = AnyMethod.new name, singleton: type == 'class'
+            method.record_location TopLevel.new file
+            method.visibility = visibility
+            add_method method
+          end
+        end
+      end
 
-    sections = (array[10] || []).map do |section|
-      [section.title, section]
-    end
+      array[9].each do |name, document, file|
+        ext = add_extend Extend.new(name, Comment.from_document(document))
+        ext.record_location TopLevel.new file
+      end if array[9] # Support Marshal version 1
+
+      sections = (array[10] || []).map do |section|
+        [section.title, section]
+      end
 
-    @sections = Hash[*sections.flatten]
-    @current_section = add_section nil
+      @sections = Hash[*sections.flatten]
+      @current_section = add_section nil
 
-    @in_files = []
+      @in_files = []
 
-    (array[11] || []).each do |filename|
-      record_location RDoc::TopLevel.new filename
+      (array[11] || []).each do |filename|
+        record_location TopLevel.new filename
+      end
+
+      @parent_name  = array[12]
+      @parent_class = array[13]
     end
 
-    @parent_name  = array[12]
-    @parent_class = array[13]
-  end
+    ##
+    # Merges +class_module+ into this ClassModule.
+    #
+    # The data in +class_module+ is preferred over the receiver.
 
-  ##
-  # Merges +class_module+ into this ClassModule.
-  #
-  # The data in +class_module+ is preferred over the receiver.
+    def merge(class_module)
+      @parent      = class_module.parent
+      @parent_name = class_module.parent_name
 
-  def merge(class_module)
-    @parent      = class_module.parent
-    @parent_name = class_module.parent_name
+      other_document = parse class_module.comment_location
 
-    other_document = parse class_module.comment_location
+      if other_document
+        document = parse @comment_location
 
-    if other_document then
-      document = parse @comment_location
+        document = document.merge other_document
 
-      document = document.merge other_document
+        @comment = Comment.from_document(document)
 
-      @comment = RDoc::Comment.from_document(document)
-      @comment_location = document
-    end
+        @comment_location = if document.parts.first.is_a?(Markup::Document)
+                              document.parts.group_by(&:file)
+                            else
+                              { document.file => [document] }
+                            end
+      end
 
-    cm = class_module
-    other_files = cm.in_files
+      cm = class_module
+      other_files = cm.in_files
 
-    merge_collections attributes, cm.attributes, other_files do |add, attr|
-      if add then
-        add_attribute attr
-      else
-        @attributes.delete attr
-        @methods_hash.delete attr.pretty_name
+      merge_collections attributes, cm.attributes, other_files do |add, attr|
+        if add
+          add_attribute attr
+        else
+          @attributes.delete attr
+          @methods_hash.delete attr.pretty_name
+        end
       end
-    end
 
-    merge_collections constants, cm.constants, other_files do |add, const|
-      if add then
-        add_constant const
-      else
-        @constants.delete const
-        @constants_hash.delete const.name
+      merge_collections constants, cm.constants, other_files do |add, const|
+        if add
+          add_constant const
+        else
+          @constants.delete const
+          @constants_hash.delete const.name
+        end
       end
-    end
 
-    merge_collections includes, cm.includes, other_files do |add, incl|
-      if add then
-        add_include incl
-      else
-        @includes.delete incl
+      merge_collections includes, cm.includes, other_files do |add, incl|
+        if add
+          add_include incl
+        else
+          @includes.delete incl
+        end
       end
-    end
 
-    @includes.uniq! # clean up
+      @includes.uniq! # clean up
 
-    merge_collections extends, cm.extends, other_files do |add, ext|
-      if add then
-        add_extend ext
-      else
-        @extends.delete ext
+      merge_collections extends, cm.extends, other_files do |add, ext|
+        if add
+          add_extend ext
+        else
+          @extends.delete ext
+        end
       end
-    end
 
-    @extends.uniq! # clean up
+      @extends.uniq! # clean up
 
-    merge_collections method_list, cm.method_list, other_files do |add, meth|
-      if add then
-        add_method meth
-      else
-        @method_list.delete meth
-        @methods_hash.delete meth.pretty_name
+      merge_collections method_list, cm.method_list, other_files do |add, meth|
+        if add
+          add_method meth
+        else
+          @method_list.delete meth
+          @methods_hash.delete meth.pretty_name
+        end
       end
+
+      merge_sections cm
+
+      self
     end
 
-    merge_sections cm
+    ##
+    # Merges collection +mine+ with +other+ preferring other.  +other_files+ is
+    # used to help determine which items should be deleted.
+    #
+    # Yields whether the item should be added or removed (true or false) and the
+    # item to be added or removed.
+    #
+    #   merge_collections things, other.things, other.in_files do |add, thing|
+    #     if add
+    #       # add the thing
+    #     else
+    #       # remove the thing
+    #     end
+    #   end
 
-    self
-  end
+    def merge_collections(mine, other, other_files, &block) # :nodoc:
+      my_things    = mine. group_by { |thing| thing.file }
+      other_things = other.group_by { |thing| thing.file }
 
-  ##
-  # Merges collection +mine+ with +other+ preferring other.  +other_files+ is
-  # used to help determine which items should be deleted.
-  #
-  # Yields whether the item should be added or removed (true or false) and the
-  # item to be added or removed.
-  #
-  #   merge_collections things, other.things, other.in_files do |add, thing|
-  #     if add then
-  #       # add the thing
-  #     else
-  #       # remove the thing
-  #     end
-  #   end
-
-  def merge_collections(mine, other, other_files, &block) # :nodoc:
-    my_things    = mine. group_by { |thing| thing.file }
-    other_things = other.group_by { |thing| thing.file }
-
-    remove_things my_things, other_files,  &block
-    add_things    my_things, other_things, &block
-  end
+      remove_things my_things, other_files,  &block
+      add_things    my_things, other_things, &block
+    end
 
-  ##
-  # Merges the comments in this ClassModule with the comments in the other
-  # ClassModule +cm+.
+    ##
+    # Merges the comments in this ClassModule with the comments in the other
+    # ClassModule +cm+.
 
-  def merge_sections(cm) # :nodoc:
-    my_sections    =    sections.group_by { |section| section.title }
-    other_sections = cm.sections.group_by { |section| section.title }
+    def merge_sections(cm) # :nodoc:
+      my_sections    =    sections.group_by { |section| section.title }
+      other_sections = cm.sections.group_by { |section| section.title }
 
-    other_files = cm.in_files
+      other_files = cm.in_files
 
-    remove_things my_sections, other_files do |_, section|
-      @sections.delete section.title
-    end
+      remove_things my_sections, other_files do |_, section|
+        @sections.delete section.title
+      end
 
-    other_sections.each do |group, sections|
-      if my_sections.include? group
-        my_sections[group].each do |my_section|
-          other_section = cm.sections_hash[group]
+      other_sections.each do |group, sections|
+        if my_sections.include? group
+          my_sections[group].each do |my_section|
+            other_section = cm.sections_hash[group]
 
-          my_comments    = my_section.comments
-          other_comments = other_section.comments
+            my_comments    = my_section.comments
+            other_comments = other_section.comments
 
-          other_files = other_section.in_files
+            other_files = other_section.in_files
 
-          merge_collections my_comments, other_comments, other_files do |add, comment|
-            if add then
-              my_section.add_comment comment
-            else
-              my_section.remove_comment comment
+            merge_collections my_comments, other_comments, other_files do |add, comment|
+              if add
+                my_section.add_comment comment
+              else
+                my_section.remove_comment comment
+              end
             end
           end
-        end
-      else
-        sections.each do |section|
-          add_section group, section.comments
+        else
+          sections.each do |section|
+            add_section group, section.comments
+          end
         end
       end
     end
-  end
 
-  ##
-  # Does this object represent a module?
+    ##
+    # Does this object represent a module?
 
-  def module?
-    false
-  end
+    def module?
+      false
+    end
 
-  ##
-  # Allows overriding the initial name.
-  #
-  # Used for modules and classes that are constant aliases.
+    ##
+    # Allows overriding the initial name.
+    #
+    # Used for modules and classes that are constant aliases.
 
-  def name=(new_name)
-    @name = new_name
-  end
+    def name=(new_name)
+      @name = new_name
+    end
 
-  ##
-  # Parses +comment_location+ into an RDoc::Markup::Document composed of
-  # multiple RDoc::Markup::Documents with their file set.
+    ##
+    # Parses +comment_location+ into an RDoc::Markup::Document composed of
+    # multiple RDoc::Markup::Documents with their file set.
 
-  def parse(comment_location)
-    case comment_location
-    when String then
-      super
-    when Array then
-      docs = comment_location.map do |comment, location|
-        doc = super comment
-        doc.file = location
+    def parse(comment_location)
+      case comment_location
+      when String
+        super
+      when Hash
+        docs = comment_location.flat_map do |location, comments|
+          comments.map do |comment|
+            doc = super comment
+            doc.file = location
+            doc
+          end
+        end
+
+        Markup::Document.new(*docs)
+      when Comment
+        doc = super comment_location.text, comment_location.format
+        doc.file = comment_location.location
         doc
+      when Markup::Document
+        return comment_location
+      else
+        raise ArgumentError, "unknown comment class #{comment_location.class}"
       end
-
-      RDoc::Markup::Document.new(*docs)
-    when RDoc::Comment then
-      doc = super comment_location.text, comment_location.format
-      doc.file = comment_location.location
-      doc
-    when RDoc::Markup::Document then
-      return comment_location
-    else
-      raise ArgumentError, "unknown comment class #{comment_location.class}"
     end
-  end
 
-  ##
-  # Path to this class or module for use with HTML generator output.
+    ##
+    # Path to this class or module for use with HTML generator output.
 
-  def path
-    prefix = options.class_module_path_prefix
-    return http_url unless prefix
-    File.join(prefix, http_url)
-  end
+    def path
+      prefix = options.class_module_path_prefix
+      return http_url unless prefix
+      File.join(prefix, http_url)
+    end
 
-  ##
-  # Name to use to generate the url:
-  # modules and classes that are aliases for another
-  # module or class return the name of the latter.
+    ##
+    # Name to use to generate the url:
+    # modules and classes that are aliases for another
+    # module or class return the name of the latter.
 
-  def name_for_path
-    is_alias_for ? is_alias_for.full_name : full_name
-  end
+    def name_for_path
+      is_alias_for ? is_alias_for.name_for_path : full_name
+    end
 
-  ##
-  # Returns the classes and modules that are not constants
-  # aliasing another class or module. For use by formatters
-  # only (caches its result).
+    ##
+    # Returns the classes and modules that are not constants
+    # aliasing another class or module. For use by formatters
+    # only (caches its result).
 
-  def non_aliases
-    @non_aliases ||= classes_and_modules.reject { |cm| cm.is_alias_for }
-  end
+    def non_aliases
+      @non_aliases ||= classes_and_modules.reject { |cm| cm.is_alias_for }
+    end
 
-  ##
-  # Updates the child modules or classes of class/module +parent+ by
-  # deleting the ones that have been removed from the documentation.
-  #
-  # +parent_hash+ is either <tt>parent.modules_hash</tt> or
-  # <tt>parent.classes_hash</tt> and +all_hash+ is ::all_modules_hash or
-  # ::all_classes_hash.
+    ##
+    # Updates the child modules or classes of class/module +parent+ by
+    # deleting the ones that have been removed from the documentation.
+    #
+    # +parent_hash+ is either <tt>parent.modules_hash</tt> or
+    # <tt>parent.classes_hash</tt> and +all_hash+ is ::all_modules_hash or
+    # ::all_classes_hash.
 
-  def remove_nodoc_children
-    prefix = self.full_name + '::'
+    def remove_nodoc_children
+      prefix = self.full_name + '::'
 
-    modules_hash.each_key do |name|
-      full_name = prefix + name
-      modules_hash.delete name unless @store.modules_hash[full_name]
-    end
+      modules_hash.each_key do |name|
+        full_name = prefix + name
+        modules_hash.delete name unless @store.modules_hash[full_name]
+      end
 
-    classes_hash.each_key do |name|
-      full_name = prefix + name
-      classes_hash.delete name unless @store.classes_hash[full_name]
+      classes_hash.each_key do |name|
+        full_name = prefix + name
+        classes_hash.delete name unless @store.classes_hash[full_name]
+      end
     end
-  end
 
-  def remove_things(my_things, other_files) # :nodoc:
-    my_things.delete_if do |file, things|
-      next false unless other_files.include? file
+    def remove_things(my_things, other_files) # :nodoc:
+      my_things.delete_if do |file, things|
+        next false unless other_files.include? file
 
-      things.each do |thing|
-        yield false, thing
+        things.each do |thing|
+          yield false, thing
+        end
+
+        true
       end
+    end
 
-      true
+    ##
+    # Search record used by RDoc::Generator::JsonIndex
+    #
+    # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+    # Use #search_snippet instead for getting documentation snippets.
+
+    def search_record
+      [
+        name,
+        full_name,
+        full_name,
+        '',
+        path,
+        '',
+        snippet(@comment_location),
+      ]
     end
-  end
 
-  ##
-  # Search record used by RDoc::Generator::JsonIndex
-
-  def search_record
-    [
-      name,
-      full_name,
-      full_name,
-      '',
-      path,
-      '',
-      snippet(@comment_location),
-    ]
-  end
+    ##
+    # Returns an HTML snippet of the first comment for search results.
 
-  ##
-  # Sets the store for this class or module and its contained code objects.
+    def search_snippet
+      first_comment = @comment_location.each_value.first&.first
+      return '' unless first_comment && !first_comment.empty?
 
-  def store=(store)
-    super
+      snippet(first_comment)
+    end
 
-    @attributes .each do |attr|  attr.store  = store end
-    @constants  .each do |const| const.store = store end
-    @includes   .each do |incl|  incl.store  = store end
-    @extends    .each do |ext|   ext.store   = store end
-    @method_list.each do |meth|  meth.store  = store end
-  end
+    ##
+    # Rebuilds +@comment+ from the current +@comment_location+ entries,
+    # skipping any empty placeholders.
 
-  ##
-  # Get the superclass of this class.  Attempts to retrieve the superclass
-  # object, returns the name if it is not known.
+    def rebuild_comment_from_location
+      texts = @comment_location.each_value.flat_map { |comments|
+        comments.filter_map { |c| c.to_s unless c.empty? }
+      }
+      merged = texts.join("\n---\n")
+      @comment = merged.empty? ? '' : Comment.new(merged)
+    end
 
-  def superclass
-    @store.find_class_named(@superclass) || @superclass
-  end
+    ##
+    # Sets the store for this class or module and its contained code objects.
 
-  ##
-  # Set the superclass of this class to +superclass+
-  #
-  # where +superclass+ is one of:
-  #
-  # - +nil+
-  # - a String containing the full name of the superclass
-  # - the RDoc::ClassModule representing the superclass
-
-  def superclass=(superclass)
-    raise NoMethodError, "#{full_name} is a module" if module?
-    case superclass
-    when RDoc::ClassModule
-      @superclass = superclass.full_name
-    when nil, String
-      @superclass = superclass
-    else
-      raise TypeError, "superclass must be a String or RDoc::ClassModule, not #{superclass.class}"
+    def store=(store)
+      super
+
+      @attributes .each do |attr|  attr.store  = store end
+      @constants  .each do |const| const.store = store end
+      @includes   .each do |incl|  incl.store  = store end
+      @extends    .each do |ext|   ext.store   = store end
+      @method_list.each do |meth|  meth.store  = store end
+    end
+
+    ##
+    # Get the superclass of this class.  Attempts to retrieve the superclass
+    # object, returns the name if it is not known.
+
+    def superclass
+      @store.find_class_named(@superclass) || @superclass
+    end
+
+    ##
+    # Set the superclass of this class to +superclass+
+    #
+    # where +superclass+ is one of:
+    #
+    # - +nil+
+    # - a String containing the full name of the superclass
+    # - the RDoc::ClassModule representing the superclass
+
+    def superclass=(superclass)
+      raise NoMethodError, "#{full_name} is a module" if module?
+      case superclass
+      when ClassModule
+        @superclass = superclass.full_name
+      when nil, String
+        @superclass = superclass
+      else
+        raise TypeError, "superclass must be a String or RDoc::ClassModule, not #{superclass.class}"
+      end
     end
-  end
 
-  ##
-  # Get all super classes of this class in an array. The last element might be
-  # a string if the name is unknown.
+    ##
+    # Get all super classes of this class in an array. The last element might be
+    # a string if the name is unknown.
 
-  def super_classes
-    result = []
-    parent = self
-    while parent = parent.superclass
-      result << parent
-      return result if parent.is_a?(String)
+    def super_classes
+      result = []
+      # Degenerate input can produce a cyclic superclass chain
+      visited = [full_name]
+      parent = self
+      while parent = parent.superclass
+        if parent.is_a?(String)
+          result << parent
+          break
+        end
+        break if visited.include?(parent.full_name)
+        visited << parent.full_name
+        result << parent
+      end
+      result
     end
-    result
-  end
 
-  def to_s # :nodoc:
-    if is_alias_for then
-      "#{self.class.name} #{self.full_name} -> #{is_alias_for}"
-    else
-      super
+    def to_s # :nodoc:
+      if is_alias_for
+        "#{self.class.name} #{self.full_name} -> #{is_alias_for}"
+      else
+        super
+      end
     end
-  end
 
-  ##
-  # 'module' or 'class'
+    ##
+    # 'module' or 'class'
+
+    def type
+      module? ? 'module' : 'class'
+    end
+
+    ##
+    # Updates the child modules & classes by replacing the ones that are
+    # aliases through a constant.
+    #
+    # The aliased module/class is replaced in the children and in
+    # RDoc::Store#modules_hash or RDoc::Store#classes_hash
+    # by a copy that has <tt>RDoc::ClassModule#is_alias_for</tt> set to
+    # the aliased module/class, and this copy is added to <tt>#aliases</tt>
+    # of the aliased module/class.
+    #
+    # Formatters can use the #non_aliases method to retrieve children that
+    # are not aliases, for instance to list the namespace content, since
+    # the aliased modules are included in the constants of the class/module,
+    # that are listed separately.
+
+    def update_aliases
+      constants.each do |const|
+        cm = const.is_alias_for
+        cm ||= const.resolved_alias_target if const.is_a?(Constant)
+        next unless cm
+
+        # Resolve chained aliases (A = B = C) to the real class/module.
+        cm = @store.find_class_or_module(cm.full_name) || cm
+        while (target = cm.is_alias_for)
+          cm = target
+        end
 
-  def type
-    module? ? 'module' : 'class'
-  end
+        cm_alias = cm.dup
+        cm_alias.name = const.name
 
-  ##
-  # Updates the child modules & classes by replacing the ones that are
-  # aliases through a constant.
-  #
-  # The aliased module/class is replaced in the children and in
-  # RDoc::Store#modules_hash or RDoc::Store#classes_hash
-  # by a copy that has <tt>RDoc::ClassModule#is_alias_for</tt> set to
-  # the aliased module/class, and this copy is added to <tt>#aliases</tt>
-  # of the aliased module/class.
-  #
-  # Formatters can use the #non_aliases method to retrieve children that
-  # are not aliases, for instance to list the namespace content, since
-  # the aliased modules are included in the constants of the class/module,
-  # that are listed separately.
-
-  def update_aliases
-    constants.each do |const|
-      next unless cm = const.is_alias_for
-      cm_alias = cm.dup
-      cm_alias.name = const.name
-
-      # Don't move top-level aliases under Object, they look ugly there
-      unless RDoc::TopLevel === cm_alias.parent then
-        cm_alias.parent = self
+        if full_name == 'Object'
+          # Don't move top-level aliases under Object, they look ugly there
+          cm_alias.parent = top_level
+        else
+          cm_alias.parent = self
+        end
         cm_alias.full_name = nil # force update for new parent
-      end
 
-      cm_alias.aliases.clear
-      cm_alias.is_alias_for = cm
+        # Don't clobber a real (non-alias) class/module already living at this
+        # name. Mirrors the BasicObject = BlankSlate guard in
+        # Context#add_module_alias. Existing alias copies (set by
+        # add_module_alias or a previous update_aliases pass) carry is_alias_for,
+        # so they're still overwritable here.
+        existing = @store.find_class_or_module(cm_alias.full_name)
+        next if existing && !existing.is_alias_for
+
+        # Persist a lazy-resolved target so Stats#report_constants and
+        # Constant#marshal_dump observe the alias relationship. Skipped
+        # aliases (above) intentionally leave the constant unmarked.
+        const.is_alias_for ||= cm
+
+        cm_alias.aliases.clear
+        cm_alias.is_alias_for = cm
+
+        if cm.module?
+          @store.modules_hash[cm_alias.full_name] = cm_alias
+          modules_hash[const.name] = cm_alias
+        else
+          @store.classes_hash[cm_alias.full_name] = cm_alias
+          classes_hash[const.name] = cm_alias
+        end
 
-      if cm.module? then
-        @store.modules_hash[cm_alias.full_name] = cm_alias
-        modules_hash[const.name] = cm_alias
-      else
-        @store.classes_hash[cm_alias.full_name] = cm_alias
-        classes_hash[const.name] = cm_alias
+        cm.aliases << cm_alias
       end
-
-      cm.aliases << cm_alias
     end
-  end
 
-  ##
-  # Deletes from #includes those whose module has been removed from the
-  # documentation.
-  #--
-  # FIXME: includes are not reliably removed, see _possible_bug test case
+    ##
+    # Deletes from #includes those whose module has been removed from the
+    # documentation.
+    #--
+    # FIXME: includes are not reliably removed, see _possible_bug test case
+
+    def update_includes
+      includes.reject! do |include|
+        mod = include.module
+        !(String === mod) && @store.modules_hash[mod.full_name].nil?
+      end
 
-  def update_includes
-    includes.reject! do |include|
-      mod = include.module
-      !(String === mod) && @store.modules_hash[mod.full_name].nil?
+      includes.uniq!
     end
 
-    includes.uniq!
-  end
+    ##
+    # Deletes from #extends those whose module has been removed from the
+    # documentation.
+    #--
+    # FIXME: like update_includes, extends are not reliably removed
 
-  ##
-  # Deletes from #extends those whose module has been removed from the
-  # documentation.
-  #--
-  # FIXME: like update_includes, extends are not reliably removed
+    def update_extends
+      extends.reject! do |ext|
+        mod = ext.module
 
-  def update_extends
-    extends.reject! do |ext|
-      mod = ext.module
+        !(String === mod) && @store.modules_hash[mod.full_name].nil?
+      end
 
-      !(String === mod) && @store.modules_hash[mod.full_name].nil?
+      extends.uniq!
     end
 
-    extends.uniq!
-  end
-
-  def embed_mixins
-    return unless options.embed_mixins
+    def embed_mixins
+      return unless options.embed_mixins
 
-    includes.each do |include|
-      next if String === include.module
-      include.module.method_list.each do |code_object|
-        add_method(prepare_to_embed(code_object))
-      end
-      include.module.constants.each do |code_object|
-        add_constant(prepare_to_embed(code_object))
-      end
-      include.module.attributes.each do |code_object|
-        add_attribute(prepare_to_embed(code_object))
+      includes.each do |include|
+        next if String === include.module
+        include.module.method_list.each do |code_object|
+          add_method(prepare_to_embed(code_object))
+        end
+        include.module.constants.each do |code_object|
+          add_constant(prepare_to_embed(code_object))
+        end
+        include.module.attributes.each do |code_object|
+          add_attribute(prepare_to_embed(code_object))
+        end
       end
-    end
 
-    extends.each do |ext|
-      next if String === ext.module
-      ext.module.method_list.each do |code_object|
-        add_method(prepare_to_embed(code_object, true))
-      end
-      ext.module.attributes.each do |code_object|
-        add_attribute(prepare_to_embed(code_object, true))
+      extends.each do |ext|
+        next if String === ext.module
+        ext.module.method_list.each do |code_object|
+          add_method(prepare_to_embed(code_object, true))
+        end
+        ext.module.attributes.each do |code_object|
+          add_attribute(prepare_to_embed(code_object, true))
+        end
       end
     end
-  end
 
   private
 
-  def prepare_to_embed(code_object, singleton=false)
-    code_object = code_object.dup
-    code_object.mixin_from = code_object.parent
-    code_object.singleton = true if singleton
-    set_current_section(code_object.section.title, code_object.section.comment)
-    # add_method and add_attribute will reassign self's visibility back to the method/attribute
-    # so we need to sync self's visibility with the object's to properly retain that information
-    self.visibility = code_object.visibility
-    code_object
+    def prepare_to_embed(code_object, singleton=false)
+      code_object = code_object.dup
+      code_object.mixin_from = code_object.parent
+      code_object.singleton = true if singleton
+      set_current_section(code_object.section.title, code_object.section.comment)
+      code_object
+    end
   end
 end