rdoc 7.1.0 → 8.0.0

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

@@ -17,11 +17,6 @@ class RDoc::Context::Section
 
   MARSHAL_VERSION = 0 # :nodoc:
 
-  ##
-  # Section comment
-
-  attr_reader :comment
-
   ##
   # Section comments
 
@@ -37,12 +32,18 @@ class RDoc::Context::Section
 
   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)
+  def initialize(parent, title, comment, store = nil)
     @parent = parent
     @title = title ? title.strip : title
+    @store = store
 
     @comments = []
 
@@ -62,10 +63,10 @@ class RDoc::Context::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?
+    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
 
@@ -97,37 +98,6 @@ class RDoc::Context::Section
     CGI.escape(title).gsub('%', '-').sub(/^-/, '')
   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
-
   def inspect # :nodoc:
     "#<%s:0x%x %p>" % [self.class, object_id, title]
   end
@@ -151,7 +121,7 @@ class RDoc::Context::Section
     [
       MARSHAL_VERSION,
       @title,
-      parse,
+      to_document,
     ]
   end
 
@@ -169,7 +139,7 @@ class RDoc::Context::Section
   # Parses +comment_location+ into an RDoc::Markup::Document composed of
   # multiple RDoc::Markup::Documents with their file set.
 
-  def parse
+  def to_document
     RDoc::Markup::Document.new(*@comments.map(&:parse))
   end
 
@@ -182,6 +152,23 @@ class RDoc::Context::Section
     @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+

data/lib/rdoc/code_object/context.rb

@@ -313,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
@@ -439,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
@@ -499,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
 
@@ -543,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
@@ -587,7 +616,7 @@ class RDoc::Context < RDoc::CodeObject
     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
 
@@ -639,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
 
   ##
@@ -785,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)
@@ -860,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.
 
@@ -939,28 +972,11 @@ class RDoc::Context < RDoc::CodeObject
     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
 
   ##

data/lib/rdoc/code_object/method_attr.rb

@@ -21,11 +21,6 @@ class RDoc::MethodAttr < RDoc::CodeObject
 
   attr_accessor :singleton
 
-  ##
-  # Source file token stream
-
-  attr_reader :text
-
   ##
   # Array of other names for this method/attribute
 
@@ -58,21 +53,26 @@ class RDoc::MethodAttr < RDoc::CodeObject
 
   attr_accessor :call_seq
 
+  ##
+  # RBS type signature lines from inline annotations or loaded .rbs files.
+  # Each entry is one overload or type expression.
+
+  attr_accessor :type_signature_lines
+
   ##
   # The call_seq or the param_seq with method name, if there is no call_seq.
 
   attr_reader :arglists
 
   ##
-  # Creates a new MethodAttr from token stream +text+ and method or attribute
+  # Creates a new MethodAttr with method or attribute
   # name +name+.
   #
   # Usually this is called by super from a subclass.
 
-  def initialize(text, name, singleton: false)
+  def initialize(name, singleton: false)
     super()
 
-    @text = text
     @name = name
 
     @aliases      = []
@@ -86,6 +86,7 @@ class RDoc::MethodAttr < RDoc::CodeObject
     @block_params = nil
     @call_seq     = nil
     @params       = nil
+    @type_signature_lines = nil
   end
 
   ##
@@ -356,13 +357,6 @@ class RDoc::MethodAttr < RDoc::CodeObject
         q.text alias_for
       end
 
-      if text then
-        q.breakable
-        q.text "text:"
-        q.breakable
-        q.pp @text
-      end
-
       unless comment.empty? then
         q.breakable
         q.text "comment:"

data/lib/rdoc/code_object/mixin.rb

@@ -71,6 +71,9 @@ class RDoc::Mixin < RDoc::CodeObject
   # lookup behavior.
   #
   # As of the beginning of October, 2011, no gem includes nonexistent modules.
+  #
+  # The Ruby parser passes an already-resolved full-path +name+, so most of this
+  # logic only runs for the C parser, which passes the unresolved local name.
 
   def module
     return @module if @module

data/lib/rdoc/code_object/top_level.rb

@@ -66,7 +66,7 @@ class RDoc::TopLevel < RDoc::Context
 
   def parser=(val)
     @parser = val
-    @store.update_parser_of_file(absolute_name, val) if @store
+    @store&.cache_text_file(relative_name)
     @parser
   end
 
@@ -149,6 +149,8 @@ class RDoc::TopLevel < RDoc::Context
     find_class_or_module(name)
   end
 
+  alias get_module_named find_module_named
+
   ##
   # Returns the relative name of this file
 
@@ -219,9 +221,15 @@ class RDoc::TopLevel < RDoc::Context
   # Path to this file for use with HTML generator output.
 
   def path
+    base = if options.main_page == full_name
+             'index.html'
+           else
+             http_url
+           end
+
     prefix = options.file_path_prefix
-    return http_url unless prefix
-    File.join(prefix, http_url)
+    return base unless prefix
+    File.join(prefix, base)
   end
 
   def pretty_print(q) # :nodoc:

data/lib/rdoc/code_object.rb

@@ -10,15 +10,12 @@
 # * RDoc::Context
 #   * RDoc::TopLevel
 #   * RDoc::ClassModule
-#     * RDoc::AnonClass (never used so far)
 #     * RDoc::NormalClass
 #     * RDoc::NormalModule
 #     * RDoc::SingleClass
 # * RDoc::MethodAttr
 #   * RDoc::Attr
 #   * RDoc::AnyMethod
-#     * RDoc::GhostMethod
-#     * RDoc::MetaMethod
 # * RDoc::Alias
 # * RDoc::Constant
 # * RDoc::Require
@@ -277,7 +274,8 @@ class RDoc::CodeObject
   # The options instance from the store this CodeObject is attached to, or a
   # default options instance if the CodeObject is not attached.
   #
-  # This is used by Text#snippet
+  # Used by: store= (visibility check), ClassModule#path, TopLevel#path,
+  #          ClassModule#embed_mixins
 
   def options
     @store&.options || RDoc::Options.new

data/lib/rdoc/comment.rb

@@ -6,7 +6,7 @@
 # Each comment may have a different markup format set by #format=.  By default
 # 'rdoc' is used.  The :markup: directive tells RDoc which format to use.
 #
-# See RDoc::MarkupReference@Directive+for+Specifying+RDoc+Source+Format.
+# See {RDoc Markup Reference}[rdoc-ref:doc/markup_reference/rdoc.rdoc@Directive+for+Specifying+RDoc+Source+Format].
 
 
 class RDoc::Comment
@@ -76,49 +76,6 @@ class RDoc::Comment
       other.text == @text and other.location == @location
   end
 
-  ##
-  # Look for a 'call-seq' in the comment to override the normal parameter
-  # handling.  The :call-seq: is indented from the baseline.  All lines of the
-  # same indentation level and prefix are consumed.
-  #
-  # For example, all of the following will be used as the :call-seq:
-  #
-  #   # :call-seq:
-  #   #   ARGF.readlines(sep=$/)     -> array
-  #   #   ARGF.readlines(limit)      -> array
-  #   #   ARGF.readlines(sep, limit) -> array
-  #   #
-  #   #   ARGF.to_a(sep=$/)     -> array
-  #   #   ARGF.to_a(limit)      -> array
-  #   #   ARGF.to_a(sep, limit) -> array
-
-  def extract_call_seq
-    # we must handle situations like the above followed by an unindented first
-    # comment.  The difficulty is to make sure not to match lines starting
-    # with ARGF at the same indent, but that are after the first description
-    # paragraph.
-    if /^(?<S> ((?!\n)\s)*+        (?# whitespaces except newline))
-         :?call-seq:
-           (?<B> \g<S>(?<N>\n|\z)  (?# trailing spaces))?
-         (?<seq>
-           (\g<S>(?!\w)\S.*\g<N>)*
-           (?>
-             (?<H> \g<S>\w+        (?# ' #   ARGF' in the example above))
-             .*\g<N>)?
-           (\g<S>\S.*\g<N>         (?# other non-blank line))*+
-           (\g<B>+(\k<H>.*\g<N>    (?# ARGF.to_a lines))++)*+
-         )
-         (?m:^\s*$|\z)
-        /x =~ @text
-      seq = $~[:seq]
-
-      all_start, all_stop = $~.offset(0)
-      @text.slice! all_start...all_stop
-
-      seq.gsub!(/^\s*/, '')
-    end
-  end
-
   ##
   # A comment is empty if its text String is empty.
 
@@ -187,28 +144,6 @@ class RDoc::Comment
     @document
   end
 
-  ##
-  # Removes private sections from this comment.  Private sections are flush to
-  # the comment marker and start with <tt>--</tt> and end with <tt>++</tt>.
-  # For C-style comments, a private marker may not start at the opening of the
-  # comment.
-  #
-  #   /*
-  #    *--
-  #    * private
-  #    *++
-  #    * public
-  #    */
-
-  def remove_private
-    # Workaround for gsub encoding for Ruby 1.9.2 and earlier
-    empty = ''
-    empty = RDoc::Encoding.change_encoding empty, @text.encoding
-
-    @text = @text.gsub(%r%^\s*([#*]?)--.*?^\s*(\1)\+\+\n?%m, empty)
-    @text = @text.sub(%r%^\s*[#*]?--.*%m, '')
-  end
-
   ##
   # Replaces this comment's text with +text+ and resets the parsed document.
   #

data/lib/rdoc/cross_reference.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'markup/attribute_manager' # for PROTECT_ATTR
-
 ##
 # RDoc::CrossReference is a reusable way to create cross references for names.
 
@@ -33,7 +31,7 @@ class RDoc::CrossReference
   # See CLASS_REGEXP_STR
 
   METHOD_REGEXP_STR = /(
-    (?!\d)[\w#{RDoc::Markup::AttributeManager::PROTECT_ATTR}]+[!?=]?|
+    (?!\d)[\w]+[!?=]?|
     %|=(?:==?|~)|![=~]|\[\]=?|<(?:<|=>?)?|>[>=]?|[-+!]@?|\*\*?|[\/%\`|&^~]
   )#{METHOD_ARGS_REGEXP_STR}/.source.delete("\n ").freeze
 
@@ -192,19 +190,13 @@ class RDoc::CrossReference
   ##
   # Returns a reference to +name+.
   #
-  # If the reference is found and +name+ is not documented +text+ will be
-  # returned.  If +name+ is escaped +name+ is returned.  If +name+ is not
-  # found +text+ is returned.
+  # If the reference is found and +name+ is not documented +nil+ will be
+  # returned.  If +name+ is not found +nil+ is returned.
 
-  def resolve(name, text)
+  def resolve(name)
     return @seen[name] if @seen.include? name
 
-    ref = case name
-          when /^\\(#{CLASS_REGEXP_STR})$/o then
-            @context.find_symbol $1
-          else
-            @context.find_symbol name
-          end
+    ref = @context.find_symbol name
 
     ref = resolve_local_symbol name unless ref
 
@@ -213,25 +205,11 @@ class RDoc::CrossReference
 
     ref = nil if RDoc::Alias === ref # external alias, can't link to it
 
-    out = if name == '\\' then
-            name
-          elsif name =~ /^\\/ then
-            # we remove the \ only in front of what we know:
-            # other backslashes are treated later, only outside of <tt>
-            ref ? $' : name
-          elsif ref then
-            if ref.display? then
-              ref
-            else
-              text
-            end
-          else
-            text
-          end
+    ref = nil unless ref&.display?
 
-    @seen[name] = out
+    @seen[name] = ref
 
-    out
+    ref
   end
 
 end

data/lib/rdoc/encoding.rb

@@ -7,13 +7,13 @@
 
 module RDoc::Encoding
 
-  HEADER_REGEXP = /^
+  HEADER_REGEXP = /\A
     (?:
-      \A\#!.*\n
+      \#!.*\n
       |
       ^\#\s+frozen[-_]string[-_]literal[=:].+\n
       |
-      ^\#[^\n]+\b(?:en)?coding[=:]\s*(?<name>[^\s;]+).*\n
+      ^\#\s*(?:-\*-\s*(?:[^;\n]*;\s*)*)?(?:en)?coding[=:]\s*(?<name>[^:\s;]+).*\n
       |
       <\?xml[^?]*encoding=(?<quote>["'])(?<name>.*?)\k<quote>.*\n
     )+

data/lib/rdoc/generator/aliki.rb

@@ -9,6 +9,8 @@ require 'uri'
 #
 
 class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
+  DESCRIPTION = 'HTML generator, written by Stan Lo'
+
   RDoc::RDoc.add_generator self
 
   def initialize(store, options)
@@ -117,6 +119,21 @@ class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
     File.write search_index_path, "var search_data = #{JSON.generate(data)};"
   end
 
+  ##
+  # Returns the type signature of +method_attr+ as HTML with linked type names.
+  # Returns nil if no type signature is present.
+
+  def type_signature_html(method_attr, from_path)
+    lines = method_attr.type_signature_lines || @store.rbs_signature_for(method_attr)
+    return unless lines
+
+    RDoc::RbsHelper.signature_to_html(
+      lines,
+      lookup: @store.type_name_lookup,
+      from_path: from_path
+    )
+  end
+
   ##
   # Resolves a URL for use in templates. Absolute URLs are returned unchanged.
   # Relative URLs are prefixed with rel_prefix to ensure they resolve correctly from any page.

data/lib/rdoc/generator/darkfish.rb

@@ -73,11 +73,6 @@ class RDoc::Generator::Darkfish
       css/rdoc.css
   ]
 
-  ##
-  # Release Version
-
-  VERSION = '3'
-
   ##
   # Description of this generator
 
@@ -173,7 +168,7 @@ class RDoc::Generator::Darkfish
   ##
   # Output progress information if debugging is enabled
 
-  def debug_msg *msg
+  def debug_msg(*msg)
     return unless $DEBUG_RDOC
     $stderr.puts(*msg)
   end
@@ -393,6 +388,8 @@ class RDoc::Generator::Darkfish
     @files.each do |file|
       current = file
 
+      next if file.text? && file.full_name == @options.main_page
+
       if file.text? and page_file.exist? then
         generate_page file
         next
@@ -580,6 +577,15 @@ class RDoc::Generator::Darkfish
 
     return unless @store
 
+    refresh_store_data
+  end
+
+  ##
+  # Refreshes the generator's data from the store.  Called by #setup and
+  # can be called again after the store has been updated (e.g. in server
+  # mode after re-parsing changed files).
+
+  def refresh_store_data
     @classes = @store.all_classes_and_modules.sort
     @files   = @store.all_files.sort
     @methods = @classes.flat_map { |m| m.method_list }.sort

data/lib/rdoc/generator/json_index.rb

@@ -118,7 +118,7 @@ class RDoc::Generator::JsonIndex
   ##
   # Output progress information if debugging is enabled
 
-  def debug_msg *msg
+  def debug_msg(*msg)
     return unless $DEBUG_RDOC
     $stderr.puts(*msg)
   end
@@ -250,7 +250,7 @@ class RDoc::Generator::JsonIndex
     debug_msg "  generating pages search index"
 
     pages = @files.select do |file|
-      file.text?
+      file.text? && file.full_name != @options.main_page
     end
 
     pages.each do |page|