rdoc 7.2.0 → 8.0.0

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

@@ -63,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
 
@@ -98,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

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
@@ -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
 
   ##
@@ -788,7 +810,7 @@ class RDoc::Context < RDoc::CodeObject
   # 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.
-  # PrismRuby parser stopped representing module nesting with parent chain at all.
+  # The Ruby parser does not represent module nesting with the parent chain.
 
   def find_enclosing_module_named(name)
     parent && parent.find_module_named(name)
@@ -950,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

@@ -72,8 +72,8 @@ class RDoc::Mixin < RDoc::CodeObject
   #
   # As of the beginning of October, 2011, no gem includes nonexistent modules.
   #
-  # When mixin is created from RDoc::Parser::PrismRuby, module name is already a resolved full-path name.
-  #
+  # 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
 
@@ -221,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

@@ -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

@@ -190,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
 
@@ -211,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|

data/lib/rdoc/generator/markup.rb

@@ -37,7 +37,15 @@ module RDoc::Generator::Markup
     options = @store.options
     this = RDoc::Context === self ? self : @parent
 
-    @formatter = RDoc::Markup::ToHtmlCrossref.new options, this.path, this
+    @formatter = RDoc::Markup::ToHtmlCrossref.new(
+      this.path, this,
+      pipe: options.pipe,
+      output_decoration: options.output_decoration,
+      hyperlink_all: options.hyperlink_all,
+      show_hash: options.show_hash,
+      autolink_excluded_words: options.autolink_excluded_words || [],
+      warn_missing_rdoc_ref: options.warn_missing_rdoc_ref
+    )
     @formatter.code_object = self
     @formatter
   end
@@ -75,60 +83,77 @@ class RDoc::CodeObject
 
 end
 
+class RDoc::AnyMethod
+
+  ##
+  # Creates an HTML link to the superclass method called by this method.
+
+  def superclass_method_link
+    target = superclass_method
+    return unless target
+
+    html_formatter = formatter
+    name = target.full_name
+
+    html_formatter.link name, html_formatter.convert_string(name)
+  end
+
+end
+
 class RDoc::MethodAttr
 
   ##
-  # Prepend +src+ with line numbers.  Relies on the first line of a source
-  # code listing having:
-  #
-  #   # File xxxxx, line dddd
-  #
-  # If it has this comment then line numbers are added to +src+ and the <tt>,
-  # line dddd</tt> portion of the comment is removed.
+  # Prepend +src+ with line numbers.
 
   def add_line_numbers(src)
-    return unless src.sub!(/\A(.*)(, line (\d+))/, '\1')
-    first = $3.to_i - 1
-    last  = first + src.count("\n")
-    size = last.to_s.length
+    return if src.empty? || !line
+    start_line = line
+    end_line  = start_line + src.count("\n")
+    number_digits = end_line.to_s.length
 
-    line = first
+    current_line = start_line
     src.gsub!(/^/) do
-      res = if line == first then
-              " " * (size + 1)
-            else
-              "<span class=\"line-num\">%2$*1$d</span> " % [size, line]
-            end
+      res = "<span class=\"line-num\">#{current_line.to_s.rjust(number_digits)}</span> "
 
-      line += 1
+      current_line += 1
       res
     end
   end
 
+  ##
+  # Prepend +src+ with a comment that declares its location in the source.
+
+  def add_location_comment(src)
+    path = CGI.escapeHTML(file.relative_name)
+    if options.line_numbers && !src.empty?
+      src.prepend("<span class=\"ruby-comment\"># File #{path}</span>\n")
+    else
+      src.prepend("<span class=\"ruby-comment\"># File #{path}, line #{line}</span>\n")
+    end
+  end
+
   ##
   # Turns the method's token stream into HTML.
   #
   # Prepends line numbers if +options.line_numbers+ is true.
 
   def markup_code
-    return '' unless @token_stream
+    return '' if !@token_stream
 
     src = RDoc::TokenStream.to_html @token_stream
 
     # dedent the source
-    indent = src.length
-    lines = src.lines.to_a
-    lines.shift if src =~ /\A.*#\ *File/i # remove '# File' comment
-    lines.each do |line|
-      if line =~ /^ *(?=\S)/
-        n = $~.end(0)
-        indent = n if n < indent
-        break if n == 0
-      end
+    common_indent = src.length
+    src.scan(/^ *(?=\S)/) do |whitespace|
+      common_indent = whitespace.length if whitespace.length < common_indent
+      break if common_indent == 0
     end
-    src.gsub!(/^#{' ' * indent}/, '') if indent > 0
+    src.gsub!(/^#{' ' * common_indent}/, '') if common_indent > 0
 
-    add_line_numbers(src) if options.line_numbers
+    if source_language == 'ruby'
+      add_line_numbers(src) if options.line_numbers
+      add_location_comment(src)
+    end
 
     src
   end