rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/{class_module.rb → code_object/class_module.rb}

@@ -30,12 +30,23 @@ class RDoc::ClassModule < RDoc::Context
   attr_accessor :constant_aliases
 
   ##
-  # Comment and the location it came from.  Use #add_comment to add comments
+  # 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
 
-  attr_accessor :diagram # :nodoc:
-
   ##
   # Class or module this constant is an alias for
 
@@ -47,16 +58,15 @@ class RDoc::ClassModule < RDoc::Context
   #--
   # TODO move to RDoc::NormalClass (I think)
 
-  def self.from_module class_type, mod
+  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
+    mod.comment_location.each do |location, comments|
+      comments.each { |comment| klass.add_comment comment, location }
     end
 
     klass.parent = mod.parent
     klass.section = mod.section
-    klass.viewer = mod.viewer
 
     klass.attributes.concat mod.attributes
     klass.method_list.concat mod.method_list
@@ -110,11 +120,10 @@ class RDoc::ClassModule < RDoc::Context
 
   def initialize(name, superclass = nil)
     @constant_aliases = []
-    @diagram          = nil
     @is_alias_for     = nil
     @name             = name
     @superclass       = superclass
-    @comment_location = [] # [[comment, location]]
+    @comment_location = {} # Hash of { location => [comments] }
 
     super()
   end
@@ -124,7 +133,7 @@ class RDoc::ClassModule < RDoc::Context
   # method is preferred over #comment= since it allows ri data to be updated
   # across multiple runs.
 
-  def add_comment comment, location
+  def add_comment(comment, location)
     return unless document_self
 
     original = comment
@@ -136,16 +145,12 @@ class RDoc::ClassModule < RDoc::Context
                 normalize_comment comment
               end
 
-    if location.parser == RDoc::Parser::C
-      @comment_location.delete_if { |(_, l)| l == location }
-    end
-
-    @comment_location << [comment, location]
+    (@comment_location[location] ||= []) << comment
 
     self.comment = original
   end
 
-  def add_things my_things, other_things # :nodoc:
+  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
@@ -177,10 +182,26 @@ class RDoc::ClassModule < RDoc::Context
   end
 
   ##
-  # HTML fragment reference for this module or class.  See
-  # RDoc::NormalClass#aref and RDoc::NormalModule#aref
+  # 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
 
   def aref
+    "#{aref_prefix}-#{full_name.downcase.gsub('::', '-')}"
+  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 legacy_aref
     "#{aref_prefix}-#{full_name}"
   end
 
@@ -202,7 +223,7 @@ class RDoc::ClassModule < RDoc::Context
   # Appends +comment+ to the current comment, but separated by a rule.  Works
   # more like <tt>+=</tt>.
 
-  def comment= comment # :nodoc:
+  def comment=(comment) # :nodoc:
     comment = case comment
               when RDoc::Comment then
                 comment.normalize
@@ -220,10 +241,12 @@ class RDoc::ClassModule < RDoc::Context
   #
   # See RDoc::Store#complete
 
-  def complete min_visibility
+  def complete(min_visibility)
     update_aliases
     remove_nodoc_children
+    embed_mixins
     update_includes
+    update_extends
     remove_invisible min_visibility
   end
 
@@ -241,7 +264,7 @@ class RDoc::ClassModule < RDoc::Context
   def documented?
     return true if @received_nodoc
     return false if @comment_location.empty?
-    @comment_location.any? { |comment, _| not comment.empty? }
+    @comment_location.each_value.any? { |comments| comments.any? { |c| not c.empty? } }
   end
 
   ##
@@ -261,7 +284,7 @@ class RDoc::ClassModule < RDoc::Context
   ##
   # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
 
-  def find_ancestor_local_symbol symbol
+  def find_ancestor_local_symbol(symbol)
     each_ancestor do |m|
       res = m.find_local_symbol(symbol)
       return res if res
@@ -273,7 +296,7 @@ class RDoc::ClassModule < RDoc::Context
   ##
   # Finds a class or module with +name+ in this namespace or its descendants
 
-  def find_class_named name
+  def find_class_named(name)
     return self if full_name == name
     return self if @name == name
 
@@ -294,6 +317,25 @@ class RDoc::ClassModule < RDoc::Context
                    end
   end
 
+  ##
+  # Return array of full_name splitted by +::+.
+
+  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}")
+    end
+  end
+
   ##
   # TODO: filter included items by #display?
 
@@ -343,7 +385,7 @@ class RDoc::ClassModule < RDoc::Context
     ]
   end
 
-  def marshal_load array # :nodoc:
+  def marshal_load(array) # :nodoc:
     initialize_visibility
     initialize_methods_etc
     @current_section   = nil
@@ -358,37 +400,39 @@ class RDoc::ClassModule < RDoc::Context
     @name       = array[1]
     @full_name  = array[2]
     @superclass = array[3]
-    @comment    = array[4]
+    document    = array[4]
 
-    @comment_location = if RDoc::Markup::Document === @comment.parts.first then
-                          @comment
+    @comment    = RDoc::Comment.from_document document
+
+    @comment_location = if document.parts.first.is_a?(RDoc::Markup::Document)
+                          document.parts.group_by(&:file)
                         else
-                          RDoc::Markup::Document.new @comment
+                          { document.file => [document] }
                         end
 
     array[5].each do |name, rw, visibility, singleton, file|
       singleton  ||= false
       visibility ||= :public
 
-      attr = RDoc::Attr.new nil, name, rw, nil, singleton
+      attr = RDoc::Attr.new name, rw, nil, singleton: singleton
 
       add_attribute attr
       attr.visibility = visibility
       attr.record_location RDoc::TopLevel.new file
     end
 
-    array[6].each do |constant, comment, file|
+    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, comment)
+        constant = add_constant RDoc::Constant.new(constant, nil, RDoc::Comment.from_document(document))
         constant.record_location RDoc::TopLevel.new file
       end
     end
 
-    array[7].each do |name, comment, file|
-      incl = add_include RDoc::Include.new(name, comment)
+    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
     end
 
@@ -397,16 +441,15 @@ class RDoc::ClassModule < RDoc::Context
         @visibility = visibility
 
         methods.each do |name, file|
-          method = RDoc::AnyMethod.new nil, name
-          method.singleton = true if type == 'class'
+          method = RDoc::AnyMethod.new name, singleton: 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)
+    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
 
@@ -432,7 +475,7 @@ class RDoc::ClassModule < RDoc::Context
   #
   # The data in +class_module+ is preferred over the receiver.
 
-  def merge class_module
+  def merge(class_module)
     @parent      = class_module.parent
     @parent_name = class_module.parent_name
 
@@ -443,7 +486,13 @@ class RDoc::ClassModule < RDoc::Context
 
       document = document.merge other_document
 
-      @comment = @comment_location = document
+      @comment = RDoc::Comment.from_document(document)
+
+      @comment_location = if document.parts.first.is_a?(RDoc::Markup::Document)
+                            document.parts.group_by(&:file)
+                          else
+                            { document.file => [document] }
+                          end
     end
 
     cm = class_module
@@ -516,7 +565,7 @@ class RDoc::ClassModule < RDoc::Context
   #     end
   #   end
 
-  def merge_collections mine, other, other_files, &block # :nodoc:
+  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 }
 
@@ -528,7 +577,7 @@ class RDoc::ClassModule < RDoc::Context
   # Merges the comments in this ClassModule with the comments in the other
   # ClassModule +cm+.
 
-  def merge_sections cm # :nodoc:
+  def merge_sections(cm) # :nodoc:
     my_sections    =    sections.group_by { |section| section.title }
     other_sections = cm.sections.group_by { |section| section.title }
 
@@ -576,7 +625,7 @@ class RDoc::ClassModule < RDoc::Context
   #
   # Used for modules and classes that are constant aliases.
 
-  def name= new_name
+  def name=(new_name)
     @name = new_name
   end
 
@@ -584,15 +633,17 @@ class RDoc::ClassModule < RDoc::Context
   # Parses +comment_location+ into an RDoc::Markup::Document composed of
   # multiple RDoc::Markup::Documents with their file set.
 
-  def parse comment_location
+  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
+    when Hash then
+      docs = comment_location.flat_map do |location, comments|
+        comments.map do |comment|
+          doc = super comment
+          doc.file = location
+          doc
+        end
       end
 
       RDoc::Markup::Document.new(*docs)
@@ -611,7 +662,9 @@ class RDoc::ClassModule < RDoc::Context
   # Path to this class or module for use with HTML generator output.
 
   def path
-    http_url @store.rdoc.generator.class_dir
+    prefix = options.class_module_path_prefix
+    return http_url unless prefix
+    File.join(prefix, http_url)
   end
 
   ##
@@ -620,7 +673,7 @@ class RDoc::ClassModule < RDoc::Context
   # module or class return the name of the latter.
 
   def name_for_path
-    is_alias_for ? is_alias_for.full_name : full_name
+    is_alias_for ? is_alias_for.name_for_path : full_name
   end
 
   ##
@@ -654,7 +707,7 @@ class RDoc::ClassModule < RDoc::Context
     end
   end
 
-  def remove_things my_things, other_files # :nodoc:
+  def remove_things(my_things, other_files) # :nodoc:
     my_things.delete_if do |file, things|
       next false unless other_files.include? file
 
@@ -668,6 +721,9 @@ class RDoc::ClassModule < RDoc::Context
 
   ##
   # 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
     [
@@ -681,10 +737,32 @@ class RDoc::ClassModule < RDoc::Context
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the first comment for search results.
+
+  def search_snippet
+    first_comment = @comment_location.each_value.first&.first
+    return '' unless first_comment && !first_comment.empty?
+
+    snippet(first_comment)
+  end
+
+  ##
+  # Rebuilds +@comment+ from the current +@comment_location+ entries,
+  # skipping any empty placeholders.
+
+  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? ? '' : RDoc::Comment.new(merged)
+  end
+
   ##
   # Sets the store for this class or module and its contained code objects.
 
-  def store= store
+  def store=(store)
     super
 
     @attributes .each do |attr|  attr.store  = store end
@@ -704,10 +782,37 @@ class RDoc::ClassModule < RDoc::Context
 
   ##
   # 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?
-    @superclass = superclass
+    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}"
+    end
+  end
+
+  ##
+  # 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)
+    end
+    result
   end
 
   def to_s # :nodoc:
@@ -742,15 +847,39 @@ class RDoc::ClassModule < RDoc::Context
 
   def update_aliases
     constants.each do |const|
-      next unless cm = const.is_alias_for
+      cm = const.is_alias_for
+      cm ||= const.resolved_alias_target if const.is_a?(RDoc::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
+
       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
+      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
-        cm_alias.full_name = nil # force update for new parent
       end
+      cm_alias.full_name = nil # force update for new parent
+
+      # 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
@@ -798,5 +927,43 @@ class RDoc::ClassModule < RDoc::Context
     extends.uniq!
   end
 
-end
+  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))
+      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))
+      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
+  end
+end

data/lib/rdoc/{constant.rb → code_object/constant.rb}

@@ -26,6 +26,14 @@ class RDoc::Constant < RDoc::CodeObject
 
   attr_accessor :visibility
 
+  ##
+  # The constant path on the RHS when the RHS is a bare constant reference
+  # (+Foo = Bar+ or +Foo = Bar::Baz+). Captured at parse time so
+  # #resolved_alias_target doesn't have to re-derive it from the textual
+  # #value. nil for other RHS shapes.
+
+  attr_accessor :is_alias_for_path
+
   ##
   # Creates a new constant with +name+, +value+ and +comment+
 
@@ -35,8 +43,9 @@ class RDoc::Constant < RDoc::CodeObject
     @name  = name
     @value = value
 
-    @is_alias_for = nil
-    @visibility   = :public
+    @is_alias_for      = nil
+    @is_alias_for_path = nil
+    @visibility        = :public
 
     self.comment = comment
   end
@@ -44,7 +53,7 @@ class RDoc::Constant < RDoc::CodeObject
   ##
   # Constants are ordered by name
 
-  def <=> other
+  def <=>(other)
     return unless self.class === other
 
     [parent_name, name] <=> [other.parent_name, other.name]
@@ -53,7 +62,7 @@ class RDoc::Constant < RDoc::CodeObject
   ##
   # Constants are equal when their #parent and #name is the same
 
-  def == other
+  def ==(other)
     self.class == other.class and
       @parent == other.parent and
       @name == other.name
@@ -83,7 +92,10 @@ class RDoc::Constant < RDoc::CodeObject
   end
 
   ##
-  # The module or class this constant is an alias for
+  # The module or class this constant is an alias for, when one was recorded
+  # explicitly (by RDoc::Context#add_module_alias, RDoc::ClassModule#update_aliases,
+  # or ri marshal load). Pure accessor; see #resolved_alias_target for the
+  # opportunistic lookup path.
 
   def is_alias_for
     case @is_alias_for
@@ -96,6 +108,20 @@ class RDoc::Constant < RDoc::CodeObject
     end
   end
 
+  ##
+  # Returns the class/module this constant *would* alias if #is_alias_for_path
+  # was set by the parser and that path resolves to a known class/module, or
+  # nil. Used to support `Const = RHS` parsed before `class RHS;end` is defined
+  # in another file. Pure lookup; does not mutate state. Honors :nodoc:
+  # (returns nil if document_self is false). Note that module nesting
+  # information is lost, so constant lookup is inaccurate.
+
+  def resolved_alias_target
+    return nil unless document_self
+    return nil unless @is_alias_for_path
+    parent.find_module_named(@is_alias_for_path)
+  end
+
   def inspect # :nodoc:
     "#<%s:0x%x %s::%s>" % [
       self.class, object_id,
@@ -132,8 +158,8 @@ class RDoc::Constant < RDoc::CodeObject
   # * #full_name
   # * #parent_name
 
-  def marshal_load array
-    initialize array[1], nil, array[5]
+  def marshal_load(array)
+    initialize array[1], nil, RDoc::Comment.from_document(array[5])
 
     @full_name     = array[2]
     @visibility    = array[3] || :public
@@ -154,7 +180,16 @@ class RDoc::Constant < RDoc::CodeObject
     "#{@parent.path}##{@name}"
   end
 
-  def pretty_print q # :nodoc:
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if comment.empty?
+
+    snippet(comment)
+  end
+
+  def pretty_print(q) # :nodoc:
     q.group 2, "[#{self.class.name} #{full_name}", "]" do
       unless comment.empty? then
         q.breakable
@@ -168,7 +203,7 @@ class RDoc::Constant < RDoc::CodeObject
   ##
   # Sets the store for this class or module and its contained code objects.
 
-  def store= store
+  def store=(store)
     super
 
     @file = @store.add_file @file.full_name if @file
@@ -184,4 +219,3 @@ class RDoc::Constant < RDoc::CodeObject
   end
 
 end
-