rdoc 3.1 → 6.3.3

data/lib/rdoc/class_module.rb

@@ -1,18 +1,39 @@
-require 'rdoc/context'
-
+# frozen_string_literal: true
 ##
 # ClassModule is the base class for objects representing either a class or a
 # module.
 
 class RDoc::ClassModule < RDoc::Context
 
-  MARSHAL_VERSION = 0 # :nodoc:
+  ##
+  # 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
 
+  ##
+  # Comment and the location it came from.  Use #add_comment to add comments
+
+  attr_accessor :comment_location
+
   attr_accessor :diagram # :nodoc:
 
   ##
@@ -23,10 +44,16 @@ class RDoc::ClassModule < RDoc::Context
   ##
   # 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
 
-  def self.from_module(class_type, mod)
-    klass = class_type.new(mod.name)
-    klass.comment = mod.comment
     klass.parent = mod.parent
     klass.section = mod.section
     klass.viewer = mod.viewer
@@ -37,6 +64,7 @@ class RDoc::ClassModule < RDoc::Context
     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
@@ -65,6 +93,7 @@ class RDoc::ClassModule < RDoc::Context
      klass.external_aliases +
      klass.constants +
      klass.includes +
+     klass.extends +
      klass.classes +
      klass.modules).each do |obj|
       obj.parent = klass
@@ -85,9 +114,48 @@ class RDoc::ClassModule < RDoc::Context
     @is_alias_for     = nil
     @name             = name
     @superclass       = superclass
+    @comment_location = [] # [[comment, location]]
+
     super()
   end
 
+  ##
+  # 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.
+
+  def add_comment comment, location
+    return unless document_self
+
+    original = comment
+
+    comment = case comment
+              when RDoc::Comment then
+                comment.normalize
+              else
+                normalize_comment comment
+              end
+
+    if location.parser == RDoc::Parser::C
+      @comment_location.delete_if { |(_, l)| l == location }
+    end
+
+    @comment_location << [comment, location]
+
+    self.comment = original
+  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
+
+      things.each do |thing|
+        yield true, thing
+      end
+    end
+  end
+
   ##
   # Ancestors list for this ClassModule: the list of included modules
   # (classes will add their superclass if any).
@@ -104,31 +172,53 @@ class RDoc::ClassModule < RDoc::Context
     includes.map { |i| i.module }.reverse
   end
 
+  def aref_prefix # :nodoc:
+    raise NotImplementedError, "missing aref_prefix for #{self.class}"
+  end
+
   ##
-  # Clears the comment. Used by the ruby parser.
+  # HTML fragment reference for this module or class.  See
+  # RDoc::NormalClass#aref and RDoc::NormalModule#aref
+
+  def aref
+    "#{aref_prefix}-#{full_name}"
+  end
+
+  ##
+  # Ancestors of this class or module only
+
+  alias direct_ancestors ancestors
+
+  ##
+  # Clears the comment. Used by the Ruby parser.
 
   def clear_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
-    return if comment.empty?
+  def comment= comment # :nodoc:
+    comment = case comment
+              when RDoc::Comment then
+                comment.normalize
+              else
+                normalize_comment comment
+              end
 
-    comment = normalize_comment comment
-    comment = "#{@comment}\n---\n#{comment}" unless
-      @comment.empty?
+    comment = "#{@comment.to_s}\n---\n#{comment.to_s}" unless @comment.empty?
 
-    super
+    super comment
   end
 
   ##
   # Prepares this ClassModule for use by a generator.
   #
-  # See RDoc::TopLevel::complete
+  # See RDoc::Store#complete
 
   def complete min_visibility
     update_aliases
@@ -137,12 +227,42 @@ class RDoc::ClassModule < RDoc::Context
     remove_invisible min_visibility
   end
 
+  ##
+  # 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
+
+  ##
+  # 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
+
+  ##
+  # 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?
+
+    ancestors.each do |mod|
+      next if String === mod
+      next if self == mod
+      yield mod
+    end
+  end
+
   ##
   # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
 
   def find_ancestor_local_symbol symbol
-    ancestors.each do |m|
-      next if m.is_a?(String)
+    each_ancestor do |m|
       res = m.find_local_symbol(symbol)
       return res if res
     end
@@ -151,7 +271,7 @@ class RDoc::ClassModule < RDoc::Context
   end
 
   ##
-  # Finds a class or module with +name+ in this namespace or its descendents
+  # Finds a class or module with +name+ in this namespace or its descendants
 
   def find_class_named name
     return self if full_name == name
@@ -167,24 +287,30 @@ class RDoc::ClassModule < RDoc::Context
   # Return the fully qualified name of this class or module
 
   def full_name
-    @full_name ||= if RDoc::ClassModule === @parent then
-                     "#{@parent.full_name}::#{@name}"
+    @full_name ||= if RDoc::ClassModule === parent then
+                     "#{parent.full_name}::#{@name}"
                    else
                      @name
                    end
   end
 
+  ##
+  # TODO: filter included items by #display?
+
   def marshal_dump # :nodoc:
-    # TODO must store the singleton attribute
     attrs = attributes.sort.map do |attr|
-      [attr.name, attr.rw]
-    end
+      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|
-          method.name
-        end
+          next unless method.display?
+          [method.name, method.file_name]
+        end.compact
 
         [visibility, method_names.uniq]
       end
@@ -196,89 +322,245 @@ class RDoc::ClassModule < RDoc::Context
       @name,
       full_name,
       @superclass,
-      parse(@comment),
+      parse(@comment_location),
       attrs,
-      constants.map do |const|
-        [const.name, parse(const.comment)]
-      end,
+      constants.select { |constant| constant.display? },
       includes.map do |incl|
-        [incl.name, parse(incl.comment)]
-      end,
+        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_load array # :nodoc:
-    # TODO must restore the singleton attribute
+    initialize_visibility
     initialize_methods_etc
-    @document_self    = true
-    @done_documenting = false
-    @current_section  = nil
-    @parent           = nil
-    @visibility       = nil
+    @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]
     @comment    = array[4]
 
-    array[5].each do |name, rw|
-      add_attribute RDoc::Attr.new(nil, name, rw, nil)
+    @comment_location = if RDoc::Markup::Document === @comment.parts.first then
+                          @comment
+                        else
+                          RDoc::Markup::Document.new @comment
+                        end
+
+    array[5].each do |name, rw, visibility, singleton, file|
+      singleton  ||= false
+      visibility ||= :public
+
+      attr = RDoc::Attr.new nil, name, rw, nil, singleton
+
+      add_attribute attr
+      attr.visibility = visibility
+      attr.record_location RDoc::TopLevel.new file
     end
 
-    array[6].each do |name, comment|
-      add_constant RDoc::Constant.new(name, nil, comment)
+    array[6].each do |constant, comment, file|
+      case constant
+      when RDoc::Constant then
+        add_constant constant
+      else
+        constant = add_constant RDoc::Constant.new(constant, nil, comment)
+        constant.record_location RDoc::TopLevel.new file
+      end
     end
 
-    array[7].each do |name, comment|
-      add_include RDoc::Include.new(name, comment)
+    array[7].each do |name, comment, file|
+      incl = add_include RDoc::Include.new(name, comment)
+      incl.record_location RDoc::TopLevel.new file
     end
 
     array[8].each do |type, visibilities|
       visibilities.each do |visibility, methods|
         @visibility = visibility
 
-        methods.each do |name|
+        methods.each do |name, file|
           method = RDoc::AnyMethod.new nil, name
           method.singleton = true if type == 'class'
+          method.record_location RDoc::TopLevel.new file
           add_method method
         end
       end
     end
+
+    array[9].each do |name, comment, file|
+      ext = add_extend RDoc::Extend.new(name, comment)
+      ext.record_location RDoc::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
+
+    @in_files = []
+
+    (array[11] || []).each do |filename|
+      record_location RDoc::TopLevel.new filename
+    end
+
+    @parent_name  = array[12]
+    @parent_class = array[13]
   end
 
   ##
-  # Merges +class_module+ into this ClassModule
+  # Merges +class_module+ into this ClassModule.
+  #
+  # The data in +class_module+ is preferred over the receiver.
 
   def merge class_module
-    comment = class_module.comment
+    @parent      = class_module.parent
+    @parent_name = class_module.parent_name
+
+    other_document = parse class_module.comment_location
 
-    if comment then
-      document = parse @comment
+    if other_document then
+      document = parse @comment_location
 
-      comment.parts.concat document.parts
+      document = document.merge other_document
 
-      @comment = comment
+      @comment = @comment_location = document
     end
 
-    class_module.each_attribute do |attr|
-      if match = attributes.find { |a| a.name == attr.name } then
-        match.rw = [match.rw, attr.rw].compact.join
-      else
+    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
       end
     end
 
-    class_module.each_constant do |const|
-      add_constant const
+    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
+      end
+    end
+
+    merge_collections includes, cm.includes, other_files do |add, incl|
+      if add then
+        add_include incl
+      else
+        @includes.delete incl
+      end
+    end
+
+    @includes.uniq! # clean up
+
+    merge_collections extends, cm.extends, other_files do |add, ext|
+      if add then
+        add_extend ext
+      else
+        @extends.delete ext
+      end
     end
 
-    class_module.each_include do |incl|
-      add_include incl
+    @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
+      end
+    end
+
+    merge_sections cm
+
+    self
+  end
+
+  ##
+  # 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
+
+  ##
+  # 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 }
+
+    other_files = cm.in_files
+
+    remove_things my_sections, other_files do |_, section|
+      @sections.delete section.title
     end
 
-    class_module.each_method do |meth|
-      add_method meth
+    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
+
+          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
+            end
+          end
+        end
+      else
+        sections.each do |section|
+          add_section group, section.comments
+        end
+      end
     end
   end
 
@@ -299,16 +581,43 @@ class RDoc::ClassModule < RDoc::Context
   end
 
   ##
-  # Path to this class or module
+  # 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
+        doc
+      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.
 
   def path
-    http_url RDoc::RDoc.current.generator.class_dir
+    http_url @store.rdoc.generator.class_dir
   end
 
   ##
   # Name to use to generate the url:
   # modules and classes that are aliases for another
-  # module or classe return the name of the latter.
+  # module or class return the name of the latter.
 
   def name_for_path
     is_alias_for ? is_alias_for.full_name : full_name
@@ -336,21 +645,61 @@ class RDoc::ClassModule < RDoc::Context
 
     modules_hash.each_key do |name|
       full_name = prefix + name
-      modules_hash.delete name unless RDoc::TopLevel.all_modules_hash[full_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 RDoc::TopLevel.all_classes_hash[full_name]
+      classes_hash.delete name unless @store.classes_hash[full_name]
+    end
+  end
+
+  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
+      end
+
+      true
     end
   end
 
+  ##
+  # Search record used by RDoc::Generator::JsonIndex
+
+  def search_record
+    [
+      name,
+      full_name,
+      full_name,
+      '',
+      path,
+      '',
+      snippet(@comment_location),
+    ]
+  end
+
+  ##
+  # Sets the store for this class or module and its contained code objects.
+
+  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
-    RDoc::TopLevel.find_class_named(@superclass) || @superclass
+    @store.find_class_named(@superclass) || @superclass
   end
 
   ##
@@ -381,7 +730,7 @@ class RDoc::ClassModule < RDoc::Context
   # aliases through a constant.
   #
   # The aliased module/class is replaced in the children and in
-  # RDoc::TopLevel::all_modules_hash or RDoc::TopLevel::all_classes_hash
+  # 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.
@@ -396,16 +745,21 @@ class RDoc::ClassModule < RDoc::Context
       next unless cm = const.is_alias_for
       cm_alias = cm.dup
       cm_alias.name = const.name
-      cm_alias.parent = self
-      cm_alias.full_name = nil  # force update for new parent
+
+      # Don't move top-level aliases under Object, they look ugly there
+      unless RDoc::TopLevel === cm_alias.parent then
+        cm_alias.parent = self
+        cm_alias.full_name = nil # force update for new parent
+      end
+
       cm_alias.aliases.clear
       cm_alias.is_alias_for = cm
 
       if cm.module? then
-        RDoc::TopLevel.all_modules_hash[cm_alias.full_name] = cm_alias
+        @store.modules_hash[cm_alias.full_name] = cm_alias
         modules_hash[const.name] = cm_alias
       else
-        RDoc::TopLevel.all_classes_hash[cm_alias.full_name] = cm_alias
+        @store.classes_hash[cm_alias.full_name] = cm_alias
         classes_hash[const.name] = cm_alias
       end
 
@@ -422,8 +776,26 @@ class RDoc::ClassModule < RDoc::Context
   def update_includes
     includes.reject! do |include|
       mod = include.module
-      !(String === mod) && RDoc::TopLevel.all_modules_hash[mod.full_name].nil?
+      !(String === mod) && @store.modules_hash[mod.full_name].nil?
+    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
+
+  def update_extends
+    extends.reject! do |ext|
+      mod = ext.module
+
+      !(String === mod) && @store.modules_hash[mod.full_name].nil?
     end
+
+    extends.uniq!
   end
 
 end