rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/code_object/context/section.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+require 'cgi/escape'
+require 'cgi/util' unless defined?(CGI::EscapeExt)
+
+##
+# A section of documentation like:
+#
+#   # :section: The title
+#   # The body
+#
+# Sections can be referenced multiple times and will be collapsed into a
+# single section.
+
+class RDoc::Context::Section
+
+  include RDoc::Text
+
+  MARSHAL_VERSION = 0 # :nodoc:
+
+  ##
+  # Section comments
+
+  attr_reader :comments
+
+  ##
+  # Context this Section lives in
+
+  attr_reader :parent
+
+  ##
+  # Section title
+
+  attr_reader :title
+
+  ##
+  # The RDoc::Store for this object.
+
+  attr_reader :store
+
+  ##
+  # Creates a new section with +title+ and +comment+
+
+  def initialize(parent, title, comment, store = nil)
+    @parent = parent
+    @title = title ? title.strip : title
+    @store = store
+
+    @comments = []
+
+    add_comment comment
+  end
+
+  ##
+  # Sections are equal when they have the same #title
+
+  def ==(other)
+    self.class === other and @title == other.title
+  end
+
+  alias eql? ==
+
+  ##
+  # Adds +comment+ to this section
+
+  def add_comment(comment)
+    Array(comment).each do |c|
+      next if c.nil?
+      raise TypeError, "unknown comment #{c.inspect}" unless RDoc::Comment === c
+      @comments << c unless c.empty?
+    end
+  end
+
+  ##
+  # Anchor reference for linking to this section using GitHub-style format.
+  #
+  # Examples:
+  #   "Section"     -> "section"
+  #   "One Two"     -> "one-two"
+  #   "[untitled]"  -> "untitled"
+
+  def aref
+    title = @title || '[untitled]'
+
+    RDoc::Text.to_anchor(title)
+  end
+
+  ##
+  # Legacy anchor reference for backward compatibility.
+  #
+  # Examples:
+  #   "Section"     -> "section"
+  #   "One Two"     -> "one+two"
+  #   "[untitled]"  -> "5Buntitled-5D"
+
+  def legacy_aref
+    title = @title || '[untitled]'
+
+    CGI.escape(title).gsub('%', '-').sub(/^-/, '')
+  end
+
+  def inspect # :nodoc:
+    "#<%s:0x%x %p>" % [self.class, object_id, title]
+  end
+
+  def hash # :nodoc:
+    @title.hash
+  end
+
+  ##
+  # The files comments in this section come from
+
+  def in_files
+    @comments.map(&:file)
+  end
+
+  ##
+  # Serializes this Section.  The title and parsed comment are saved, but not
+  # the section parent which must be restored manually.
+
+  def marshal_dump
+    [
+      MARSHAL_VERSION,
+      @title,
+      to_document,
+    ]
+  end
+
+  ##
+  # De-serializes this Section.  The section parent must be restored manually.
+
+  def marshal_load(array)
+    @parent  = nil
+
+    @title    = array[1]
+    @comments = array[2].parts.map { |doc| RDoc::Comment.from_document(doc) }
+  end
+
+  ##
+  # Parses +comment_location+ into an RDoc::Markup::Document composed of
+  # multiple RDoc::Markup::Documents with their file set.
+
+  def to_document
+    RDoc::Markup::Document.new(*@comments.map(&:parse))
+  end
+
+  ##
+  # The section's title, or 'Top Section' if the title is nil.
+  #
+  # This is used by the table of contents template so the name is silly.
+
+  def plain_html
+    @title || 'Top Section'
+  end
+
+  ##
+  # Section comment
+
+  def comment
+    return nil if @comments.empty?
+    RDoc::Comment.from_document(to_document)
+  end
+
+  def description
+    return '' if @comments.empty?
+    markup comment
+  end
+
+  def language
+    @comments.first&.language
+  end
+
+  ##
+  # Removes a comment from this section if it is from the same file as
+  # +comment+
+
+  def remove_comment(target_comment)
+    @comments.delete_if do |stored_comment|
+      stored_comment.file == target_comment.file
+    end
+  end
+
+end

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

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
-require 'cgi'
-
 ##
 # A Context is something that can hold modules, classes, methods, attributes,
 # aliases, requires, and includes. Classes, modules, and files are all
@@ -182,7 +180,7 @@ class RDoc::Context < RDoc::CodeObject
   #
   # Currently only RDoc::Extend and RDoc::Include are supported.
 
-  def add klass, name, comment
+  def add(klass, name, comment)
     if RDoc::Extend == klass then
       ext = RDoc::Extend.new name, comment
       add_extend ext
@@ -197,7 +195,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Adds +an_alias+ that is automatically resolved
 
-  def add_alias an_alias
+  def add_alias(an_alias)
     return an_alias unless @document_self
 
     method_attr = find_method(an_alias.old_name, an_alias.singleton) ||
@@ -224,7 +222,7 @@ class RDoc::Context < RDoc::CodeObject
   # if method +foo+ exists, but <tt>attr_accessor :foo</tt> will be registered
   # if method +foo+ exists, but <tt>foo=</tt> does not.
 
-  def add_attribute attribute
+  def add_attribute(attribute)
     return attribute unless @document_self
 
     # mainly to check for redefinition of an attribute as a method
@@ -287,7 +285,7 @@ class RDoc::Context < RDoc::CodeObject
   # unless it later sees <tt>class Container</tt>.  +add_class+ automatically
   # upgrades +given_name+ to a class in this case.
 
-  def add_class class_type, given_name, superclass = '::Object'
+  def add_class(class_type, given_name, superclass = '::Object')
     # superclass +nil+ is passed by the C parser in the following cases:
     # - registering Object in 1.8 (correct)
     # - registering BasicObject in 1.9 (correct)
@@ -315,13 +313,7 @@ class RDoc::Context < RDoc::CodeObject
                       @store.modules_hash[given_name]
           return enclosing if enclosing
           # not found: create the parent(s)
-          names = ename.split('::')
-          enclosing = self
-          names.each do |n|
-            enclosing = enclosing.classes_hash[n] ||
-                        enclosing.modules_hash[n] ||
-                        enclosing.add_module(RDoc::NormalModule, n)
-          end
+          enclosing = find_or_create_namespace_path ename
         end
       else
         name = full_name
@@ -403,7 +395,7 @@ class RDoc::Context < RDoc::CodeObject
   # unless #done_documenting is +true+. Sets the #parent of +mod+
   # to +self+, and its #section to #current_section. Returns +mod+.
 
-  def add_class_or_module mod, self_hash, all_hash
+  def add_class_or_module(mod, self_hash, all_hash)
     mod.section = current_section # TODO declaring context? something is
                                   # wrong here...
     mod.parent = self
@@ -428,7 +420,7 @@ class RDoc::Context < RDoc::CodeObject
   # Adds +constant+ if not already there. If it is, updates the comment,
   # value and/or is_alias_for of the known constant if they were empty/nil.
 
-  def add_constant constant
+  def add_constant(constant)
     return constant unless @document_self
 
     # HACK: avoid duplicate 'PI' & 'E' in math.c (1.8.7 source code)
@@ -441,6 +433,7 @@ class RDoc::Context < RDoc::CodeObject
       known.value = constant.value if
         known.value.nil? or known.value.strip.empty?
 
+      constant.parent = self
       known.is_alias_for ||= constant.is_alias_for
     else
       @constants_hash[constant.name] = constant
@@ -453,7 +446,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Adds included module +include+ which should be an RDoc::Include
 
-  def add_include include
+  def add_include(include)
     add_to @includes, include
 
     include
@@ -462,7 +455,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Adds extension module +ext+ which should be an RDoc::Extend
 
-  def add_extend ext
+  def add_extend(ext)
     add_to @extends, ext
 
     ext
@@ -472,7 +465,7 @@ class RDoc::Context < RDoc::CodeObject
   # Adds +method+ if not already there. If it is (as method or attribute),
   # updates the comment if it was empty.
 
-  def add_method method
+  def add_method(method)
     return method unless @document_self
 
     # HACK: avoid duplicate 'new' in io.c & struct.c (1.8.7 source code)
@@ -484,7 +477,7 @@ class RDoc::Context < RDoc::CodeObject
         known.comment = method.comment if known.comment.empty?
         previously = ", previously in #{known.file}" unless
           method.file == known.file
-        @store.rdoc.options.warn \
+        @store.options.warn \
           "Duplicate method #{known.full_name} in #{method.file}#{previously}"
       end
     else
@@ -501,11 +494,44 @@ class RDoc::Context < RDoc::CodeObject
     method
   end
 
+  ##
+  # Returns the owner context and local name for +constant_path+, creating
+  # missing namespace modules. A leading +::+ resolves from the top-level.
+  # This only resolves explicit context-tree paths; RDoc::Parser::Ruby has
+  # parser-local lexical helpers for Ruby's nesting-dependent lookup.
+
+  def find_or_create_constant_owner_for_path(constant_path) # :nodoc:
+    constant_path = constant_path.to_s
+    owner = constant_path.start_with?('::') ? top_level : self
+    constant_path = constant_path.delete_prefix('::')
+
+    owner_path, separator, name = constant_path.rpartition('::')
+    owner = owner.find_or_create_namespace_path owner_path unless separator.empty?
+
+    [owner, name]
+  end
+
+  ##
+  # Finds or creates the module namespace path under this context.
+
+  def find_or_create_namespace_path(path) # :nodoc:
+    path.to_s.split('::').inject(self) do |owner, name|
+      owner.classes_hash[name] ||
+        owner.modules_hash[name] ||
+        owner.add_module(RDoc::NormalModule, name)
+    end
+  end
+
   ##
   # Adds a module named +name+.  If RDoc already knows +name+ is a class then
   # that class is returned instead.  See also #add_class.
 
   def add_module(class_type, name)
+    if name.to_s.include?('::')
+      owner, name = find_or_create_constant_owner_for_path name
+      return owner.add_module class_type, name unless owner == self
+    end
+
     mod = @classes[name] || @modules[name]
     return mod if mod
 
@@ -526,7 +552,7 @@ class RDoc::Context < RDoc::CodeObject
   # Adds an alias from +from+ (a class or module) to +name+ which was defined
   # in +file+.
 
-  def add_module_alias from, from_name, to, file
+  def add_module_alias(from, from_name, to, file)
     return from if @done_documenting
 
     to_full_name = child_name to.name
@@ -545,6 +571,7 @@ class RDoc::Context < RDoc::CodeObject
     new_to = from.dup
     new_to.name = to.name
     new_to.full_name = nil
+    new_to.is_alias_for = from
 
     if new_to.module? then
       @store.modules_hash[to_full_name] = new_to
@@ -585,11 +612,11 @@ class RDoc::Context < RDoc::CodeObject
   #
   # See also RDoc::Context::Section
 
-  def add_section title, comment = nil
+  def add_section(title, comment = nil)
     if section = @sections[title] then
       section.add_comment comment if comment
     else
-      section = Section.new self, title, comment
+      section = Section.new self, title, comment, @store
       @sections[title] = section
     end
 
@@ -599,7 +626,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Adds +thing+ to the collection +array+
 
-  def add_to array, thing
+  def add_to(array, thing)
     array << thing if @document_self
 
     thing.parent  = self
@@ -631,7 +658,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Creates the full name for a child with +name+
 
-  def child_name name
+  def child_name(name)
     if name =~ /^:+/
       $'  #'
     elsif RDoc::TopLevel === self then
@@ -641,18 +668,11 @@ class RDoc::Context < RDoc::CodeObject
     end
   end
 
-  ##
-  # Class attributes
-
-  def class_attributes
-    @class_attributes ||= attributes.select { |a| a.singleton }
-  end
-
   ##
   # Class methods
 
   def class_method_list
-    @class_method_list ||= method_list.select { |a| a.singleton }
+    method_list.select { |a| a.singleton }
   end
 
   ##
@@ -690,13 +710,6 @@ class RDoc::Context < RDoc::CodeObject
     section
   end
 
-  ##
-  # Is part of this thing was defined in +file+?
-
-  def defined_in?(file)
-    @in_files.include?(file)
-  end
-
   def display(method_attr) # :nodoc:
     if method_attr.is_a? RDoc::Attr
       "#{method_attr.definition} #{method_attr.pretty_name}"
@@ -712,14 +725,7 @@ class RDoc::Context < RDoc::CodeObject
   # This method exists to make it easy to work with Context subclasses that
   # aren't part of RDoc.
 
-  def each_ancestor # :nodoc:
-  end
-
-  ##
-  # Iterator for attributes
-
-  def each_attribute # :yields: attribute
-    @attributes.each { |a| yield a }
+  def each_ancestor(&_) # :nodoc:
   end
 
   ##
@@ -729,27 +735,6 @@ class RDoc::Context < RDoc::CodeObject
     classes_and_modules.sort.each(&block)
   end
 
-  ##
-  # Iterator for constants
-
-  def each_constant # :yields: constant
-    @constants.each {|c| yield c}
-  end
-
-  ##
-  # Iterator for included modules
-
-  def each_include # :yields: include
-    @includes.each do |i| yield i end
-  end
-
-  ##
-  # Iterator for extension modules
-
-  def each_extend # :yields: extend
-    @extends.each do |e| yield e end
-  end
-
   ##
   # Iterator for methods
 
@@ -822,7 +807,10 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
-  # Find a module at a higher scope
+  # Tries to find a module at a higher scope.
+  # But parent is not always a higher module nesting scope, so the result is not correct.
+  # Parent chain can only represent last-opened nesting, and may be broken in some cases.
+  # The Ruby parser does not represent module nesting with the parent chain.
 
   def find_enclosing_module_named(name)
     parent && parent.find_module_named(name)
@@ -849,13 +837,6 @@ class RDoc::Context < RDoc::CodeObject
     end
   end
 
-  ##
-  # Finds a file with +name+ in this context
-
-  def find_file_named name
-    @store.find_file_named name
-  end
-
   ##
   # Finds an instance method with +name+ in this context
 
@@ -873,7 +854,7 @@ class RDoc::Context < RDoc::CodeObject
     find_attribute_named(symbol) or
     find_external_alias_named(symbol) or
     find_module_named(symbol) or
-    find_file_named(symbol)
+    @store.find_file_named(symbol)
   end
 
   ##
@@ -904,15 +885,23 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
-  # Find a module with +name+ using ruby's scoping rules
+  # Find a module with +name+ trying to using ruby's scoping rules.
+  # find_enclosing_module_named cannot use ruby's scoping so the result is not correct.
 
   def find_module_named(name)
-    res = @modules[name] || @classes[name]
+    res = get_module_named(name)
     return res if res
     return self if self.name == name
     find_enclosing_module_named name
   end
 
+  # Get a module named +name+ in this context
+  # Don't look up for higher module nesting scopes. RDoc::Context doesn't have that information.
+
+  def get_module_named(name)
+    @modules[name] || @classes[name]
+  end
+
   ##
   # Look up +symbol+, first as a module, then as a local symbol.
 
@@ -975,36 +964,19 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # URL for this with a +prefix+
 
-  def http_url(prefix)
+  def http_url
     path = name_for_path
     path = path.gsub(/<<\s*(\w*)/, 'from-\1') if path =~ /<</
-    path = [prefix] + path.split('::')
+    path = path.split('::')
 
     File.join(*path.compact) + '.html'
   end
 
-  ##
-  # Instance attributes
-
-  def instance_attributes
-    @instance_attributes ||= attributes.reject { |a| a.singleton }
-  end
-
   ##
   # Instance methods
 
   def instance_methods
-    @instance_methods ||= method_list.reject { |a| a.singleton }
-  end
-
-  ##
-  # Instance methods
-  #--
-  # TODO remove this later
-
-  def instance_method_list
-    warn '#instance_method_list is obsoleted, please use #instance_methods'
-    @instance_methods ||= method_list.reject { |a| a.singleton }
+    method_list.reject { |a| a.singleton }
   end
 
   ##
@@ -1014,7 +986,7 @@ class RDoc::Context < RDoc::CodeObject
   # If +section+ is provided only methods in that RDoc::Context::Section will
   # be returned.
 
-  def methods_by_type section = nil
+  def methods_by_type(section = nil)
     methods = {}
 
     TYPES.each do |type|
@@ -1106,7 +1078,7 @@ class RDoc::Context < RDoc::CodeObject
   #--
   # TODO mark the visibility of attributes in the template (if not public?)
 
-  def remove_invisible min_visibility
+  def remove_invisible(min_visibility)
     return if [:private, :nodoc].include? min_visibility
     remove_invisible_in @method_list, min_visibility
     remove_invisible_in @attributes, min_visibility
@@ -1116,7 +1088,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Only called when min_visibility == :public or :private
 
-  def remove_invisible_in array, min_visibility # :nodoc:
+  def remove_invisible_in(array, min_visibility) # :nodoc:
     if min_visibility == :public then
       array.reject! { |e|
         e.visibility != :public and not e.force_documentation
@@ -1132,7 +1104,7 @@ class RDoc::Context < RDoc::CodeObject
   # Tries to resolve unmatched aliases when a method or attribute has just
   # been added.
 
-  def resolve_aliases added
+  def resolve_aliases(added)
     # resolve any pending unmatched aliases
     key = added.pretty_name
     unmatched_alias_list = @unmatched_alias_lists[key]
@@ -1183,7 +1155,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Sets the current section to a section with +title+.  See also #add_section
 
-  def set_current_section title, comment
+  def set_current_section(title, comment)
     @current_section = add_section title, comment
   end
 
@@ -1248,7 +1220,7 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Upgrades NormalModule +mod+ in +enclosing+ to a +class_type+
 
-  def upgrade_to_class mod, class_type, enclosing
+  def upgrade_to_class(mod, class_type, enclosing)
     enclosing.modules_hash.delete mod.name
 
     klass = RDoc::ClassModule.from_module class_type, mod
@@ -1261,6 +1233,6 @@ class RDoc::Context < RDoc::CodeObject
     klass
   end
 
-  autoload :Section, 'rdoc/context/section'
+  autoload :Section, "#{__dir__}/context/section"
 
 end

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

@@ -7,4 +7,3 @@
 class RDoc::Extend < RDoc::Mixin
 
 end
-

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

@@ -7,4 +7,3 @@
 class RDoc::Include < RDoc::Mixin
 
 end
-