rdoc 6.17.0 → 8.1.0

data/lib/rdoc/code_object/constant.rb

@@ -1,186 +1,223 @@
 # frozen_string_literal: true
-##
-# A constant
+module RDoc
+  ##
+  # A constant
 
-class RDoc::Constant < RDoc::CodeObject
+  class Constant < CodeObject
 
-  MARSHAL_VERSION = 0 # :nodoc:
+    MARSHAL_VERSION = 0 # :nodoc:
 
-  ##
-  # Sets the module or class this is constant is an alias for.
+    ##
+    # Sets the module or class this is constant is an alias for.
 
-  attr_writer :is_alias_for
+    attr_writer :is_alias_for
 
-  ##
-  # The constant's name
+    ##
+    # The constant's name
 
-  attr_accessor :name
+    attr_accessor :name
 
-  ##
-  # The constant's value
+    ##
+    # The constant's value
 
-  attr_accessor :value
+    attr_accessor :value
 
-  ##
-  # The constant's visibility
+    ##
+    # The constant's visibility
 
-  attr_accessor :visibility
+    attr_accessor :visibility
 
-  ##
-  # Creates a new constant with +name+, +value+ and +comment+
+    ##
+    # 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.
 
-  def initialize(name, value, comment)
-    super()
+    attr_accessor :is_alias_for_path
 
-    @name  = name
-    @value = value
+    ##
+    # Creates a new constant with +name+, +value+ and +comment+
 
-    @is_alias_for = nil
-    @visibility   = :public
+    def initialize(name, value, comment)
+      super()
 
-    self.comment = comment
-  end
+      @name  = name
+      @value = value
 
-  ##
-  # Constants are ordered by name
+      @is_alias_for      = nil
+      @is_alias_for_path = nil
+      @visibility        = :public
 
-  def <=>(other)
-    return unless self.class === other
+      self.comment = comment
+    end
 
-    [parent_name, name] <=> [other.parent_name, other.name]
-  end
+    ##
+    # Constants are ordered by name
 
-  ##
-  # Constants are equal when their #parent and #name is the same
+    def <=>(other)
+      return unless self.class === other
 
-  def ==(other)
-    self.class == other.class and
-      @parent == other.parent and
-      @name == other.name
-  end
+      [parent_name, name] <=> [other.parent_name, other.name]
+    end
 
-  ##
-  # A constant is documented if it has a comment, or is an alias
-  # for a documented class or module.
-
-  def documented?
-    return true if super
-    return false unless @is_alias_for
-    case @is_alias_for
-    when String then
-      found = @store.find_class_or_module @is_alias_for
-      return false unless found
-      @is_alias_for = found
+    ##
+    # Constants are equal when their #parent and #name is the same
+
+    def ==(other)
+      self.class == other.class and
+        @parent == other.parent and
+        @name == other.name
     end
-    @is_alias_for.documented?
-  end
 
-  ##
-  # Full constant name including namespace
+    ##
+    # A constant is documented if it has a comment, or is an alias
+    # for a documented class or module.
+
+    def documented?
+      return true if super
+      return false unless @is_alias_for
+      case @is_alias_for
+      when String
+        found = @store.find_class_or_module @is_alias_for
+        return false unless found
+        @is_alias_for = found
+      end
+      @is_alias_for.documented?
+    end
 
-  def full_name
-    @full_name ||= "#{parent_name}::#{@name}"
-  end
+    ##
+    # Full constant name including namespace
 
-  ##
-  # The module or class this constant is an alias for
-
-  def is_alias_for
-    case @is_alias_for
-    when String then
-      found = @store.find_class_or_module @is_alias_for
-      @is_alias_for = found if found
-      @is_alias_for
-    else
-      @is_alias_for
+    def full_name
+      @full_name ||= "#{parent_name}::#{@name}"
     end
-  end
 
-  def inspect # :nodoc:
-    "#<%s:0x%x %s::%s>" % [
-      self.class, object_id,
-      parent_name, @name,
-    ]
-  end
+    ##
+    # 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
+      when String
+        found = @store.find_class_or_module @is_alias_for
+        @is_alias_for = found if found
+        @is_alias_for
+      else
+        @is_alias_for
+      end
+    end
 
-  ##
-  # Dumps this Constant for use by ri.  See also #marshal_load
-
-  def marshal_dump
-    alias_name = case found = is_alias_for
-                 when RDoc::CodeObject then found.full_name
-                 else                       found
-                 end
-
-    [ MARSHAL_VERSION,
-      @name,
-      full_name,
-      @visibility,
-      alias_name,
-      parse(@comment),
-      @file.relative_name,
-      parent.name,
-      parent.class,
-      section.title,
-    ]
-  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
 
-  ##
-  # Loads this Constant from +array+.  For a loaded Constant the following
-  # methods will return cached values:
-  #
-  # * #full_name
-  # * #parent_name
-
-  def marshal_load(array)
-    initialize array[1], nil, RDoc::Comment.from_document(array[5])
-
-    @full_name     = array[2]
-    @visibility    = array[3] || :public
-    @is_alias_for  = array[4]
-    #                      5 handled above
-    #                      6 handled below
-    @parent_name   = array[7]
-    @parent_class  = array[8]
-    @section_title = array[9]
-
-    @file = RDoc::TopLevel.new array[6]
-  end
+    def inspect # :nodoc:
+      "#<%s:0x%x %s::%s>" % [
+        self.class, object_id,
+        parent_name, @name,
+      ]
+    end
 
-  ##
-  # Path to this constant for use with HTML generator output.
+    ##
+    # Dumps this Constant for use by ri.  See also #marshal_load
+
+    def marshal_dump
+      alias_name = case found = is_alias_for
+                   when CodeObject then found.full_name
+                   else                       found
+                   end
+
+      [ MARSHAL_VERSION,
+        @name,
+        full_name,
+        @visibility,
+        alias_name,
+        parse(@comment),
+        @file.relative_name,
+        parent.name,
+        parent.class,
+        section.title,
+      ]
+    end
 
-  def path
-    "#{@parent.path}##{@name}"
-  end
+    ##
+    # Loads this Constant from +array+.  For a loaded Constant the following
+    # methods will return cached values:
+    #
+    # * #full_name
+    # * #parent_name
+
+    def marshal_load(array)
+      initialize array[1], nil, Comment.from_document(array[5])
+
+      @full_name     = array[2]
+      @visibility    = array[3] || :public
+      @is_alias_for  = array[4]
+      #                      5 handled above
+      #                      6 handled below
+      @parent_name   = array[7]
+      @parent_class  = array[8]
+      @section_title = array[9]
+
+      @file = TopLevel.new array[6]
+    end
+
+    ##
+    # Path to this constant for use with HTML generator output.
+
+    def path
+      "#{@parent.path}##{@name}"
+    end
+
+    ##
+    # Returns an HTML snippet of the comment for search results.
+
+    def search_snippet
+      return '' if comment.empty?
 
-  def pretty_print(q) # :nodoc:
-    q.group 2, "[#{self.class.name} #{full_name}", "]" do
-      unless comment.empty? then
-        q.breakable
-        q.text "comment:"
-        q.breakable
-        q.pp @comment
+      snippet(comment)
+    end
+
+    def pretty_print(q) # :nodoc:
+      q.group 2, "[#{self.class.name} #{full_name}", "]" do
+        unless comment.empty?
+          q.breakable
+          q.text "comment:"
+          q.breakable
+          q.pp @comment
+        end
       end
     end
-  end
 
-  ##
-  # Sets the store for this class or module and its contained code objects.
+    ##
+    # Sets the store for this class or module and its contained code objects.
 
-  def store=(store)
-    super
+    def store=(store)
+      super
 
-    @file = @store.add_file @file.full_name if @file
-  end
+      @file = @store.add_file @file.full_name if @file
+    end
 
-  def to_s # :nodoc:
-    parent_name = parent ? parent.full_name : '(unknown)'
-    if is_alias_for
-      "constant #{parent_name}::#@name -> #{is_alias_for}"
-    else
-      "constant #{parent_name}::#@name"
+    def to_s # :nodoc:
+      parent_name = parent ? parent.full_name : '(unknown)'
+      if is_alias_for
+        "constant #{parent_name}::#@name -> #{is_alias_for}"
+      else
+        "constant #{parent_name}::#@name"
+      end
     end
-  end
 
+  end
 end

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

@@ -2,175 +2,185 @@
 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.
+module RDoc
+  class Context
+    ##
+    # 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
+    class Section
 
-  include RDoc::Text
+      include Text
 
-  MARSHAL_VERSION = 0 # :nodoc:
+      MARSHAL_VERSION = 0 # :nodoc:
 
-  ##
-  # Section comment
+      ##
+      # Section comments
 
-  attr_reader :comment
+      attr_reader :comments
 
-  ##
-  # Section comments
+      ##
+      # Context this Section lives in
 
-  attr_reader :comments
+      attr_reader :parent
 
-  ##
-  # Context this Section lives in
+      ##
+      # Section title
 
-  attr_reader :parent
+      attr_reader :title
 
-  ##
-  # Section title
+      ##
+      # The RDoc::Store for this object.
 
-  attr_reader :title
+      attr_reader :store
 
-  ##
-  # Creates a new section with +title+ and +comment+
+      ##
+      # Creates a new section with +title+ and +comment+
 
-  def initialize(parent, title, comment)
-    @parent = parent
-    @title = title ? title.strip : title
+      def initialize(parent, title, comment, store = nil)
+        @parent = parent
+        @title = title ? title.strip : title
+        @store = store
 
-    @comments = []
+        @comments = []
 
-    add_comment comment
-  end
+        add_comment comment
+      end
 
-  ##
-  # Sections are equal when they have the same #title
+      ##
+      # Sections are equal when they have the same #title
 
-  def ==(other)
-    self.class === other and @title == other.title
-  end
+      def ==(other)
+        self.class === other and @title == other.title
+      end
 
-  alias eql? ==
+      alias eql? ==
 
-  ##
-  # Adds +comment+ to this section
+      ##
+      # Adds +comment+ to this section
 
-  def add_comment(comment)
-    comments = Array(comment)
-    comments.each do |c|
-      extracted_comment = extract_comment(c)
-      @comments << extracted_comment unless extracted_comment.empty?
-    end
-  end
+      def add_comment(comment)
+        Array(comment).each do |c|
+          next if c.nil?
+          raise TypeError, "unknown comment #{c.inspect}" unless Comment === c
+          @comments << c unless c.empty?
+        end
+      end
 
-  ##
-  # Anchor reference for linking to this section
+      ##
+      # 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]'
+      def aref
+        title = @title || '[untitled]'
 
-    CGI.escape(title).gsub('%', '-').sub(/^-/, '')
-  end
+        Text.to_anchor(title)
+      end
 
-  ##
-  # Extracts the comment for this section from the original comment block.
-  # If the first line contains :section:, strip it and use the rest.
-  # Otherwise remove lines up to the line containing :section:, and look
-  # for those lines again at the end and remove them. This lets us write
-  #
-  #   # :section: The title
-  #   # The body
-
-  def extract_comment(comment)
-    case comment
-    when nil
-      RDoc::Comment.new ''
-    when RDoc::Comment then
-      if comment.text =~ /^#[ \t]*:section:.*\n/ then
-        start = $`
-        rest = $'
-
-        comment.text = if start.empty? then
-                         rest
-                       else
-                         rest.sub(/#{start.chomp}\Z/, '')
-                       end
-      end
-
-      comment
-    else
-      raise TypeError, "unknown comment #{comment.inspect}"
-    end
-  end
+      ##
+      # Legacy anchor reference for backward compatibility.
+      #
+      # Examples:
+      #   "Section"     -> "section"
+      #   "One Two"     -> "one+two"
+      #   "[untitled]"  -> "5Buntitled-5D"
 
-  def inspect # :nodoc:
-    "#<%s:0x%x %p>" % [self.class, object_id, title]
-  end
+      def legacy_aref
+        title = @title || '[untitled]'
 
-  def hash # :nodoc:
-    @title.hash
-  end
+        CGI.escape(title).gsub('%', '-').sub(/^-/, '')
+      end
 
-  ##
-  # The files comments in this section come from
+      def inspect # :nodoc:
+        "#<%s:0x%x %p>" % [self.class, object_id, title]
+      end
 
-  def in_files
-    @comments.map(&:file)
-  end
+      def hash # :nodoc:
+        @title.hash
+      end
 
-  ##
-  # Serializes this Section.  The title and parsed comment are saved, but not
-  # the section parent which must be restored manually.
+      ##
+      # The files comments in this section come from
 
-  def marshal_dump
-    [
-      MARSHAL_VERSION,
-      @title,
-      parse,
-    ]
-  end
+      def in_files
+        @comments.map(&:file)
+      end
 
-  ##
-  # De-serializes this Section.  The section parent must be restored manually.
+      ##
+      # Serializes this Section.  The title and parsed comment are saved, but not
+      # the section parent which must be restored manually.
 
-  def marshal_load(array)
-    @parent  = nil
+      def marshal_dump
+        [
+          MARSHAL_VERSION,
+          @title,
+          to_document,
+        ]
+      end
 
-    @title    = array[1]
-    @comments = array[2].parts.map { |doc| RDoc::Comment.from_document(doc) }
-  end
+      ##
+      # De-serializes this Section.  The section parent must be restored manually.
 
-  ##
-  # Parses +comment_location+ into an RDoc::Markup::Document composed of
-  # multiple RDoc::Markup::Documents with their file set.
+      def marshal_load(array)
+        @parent  = nil
 
-  def parse
-    RDoc::Markup::Document.new(*@comments.map(&:parse))
-  end
+        @title    = array[1]
+        @comments = array[2].parts.map { |doc| Comment.from_document(doc) }
+      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.
+      ##
+      # Parses +comment_location+ into an RDoc::Markup::Document composed of
+      # multiple RDoc::Markup::Documents with their file set.
 
-  def plain_html
-    @title || 'Top Section'
-  end
+      def to_document
+        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.
 
-  ##
-  # Removes a comment from this section if it is from the same file as
-  # +comment+
+      def plain_html
+        @title || 'Top Section'
+      end
+
+      ##
+      # Section comment
+
+      def comment
+        return nil if @comments.empty?
+        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
 
-  def remove_comment(target_comment)
-    @comments.delete_if do |stored_comment|
-      stored_comment.file == target_comment.file
     end
   end
-
 end