rdoc 6.15.1 → 7.1.0

data/lib/rdoc/code_object/any_method.rb

@@ -351,7 +351,6 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     return call_seq unless is_alias_for || !aliases.empty?
 
     method_name = self.name
-    method_name = method_name[0, 1] if method_name =~ /\A\[/
 
     entries = call_seq.split "\n"
 
@@ -360,15 +359,24 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       ignore << is_alias_for.name
       ignore.concat is_alias_for.aliases.map(&:name)
     end
-    ignore.map! { |n| n =~ /\A\[/ ? /\[.*\]/ : n}
+
     ignore.delete(method_name)
-    ignore = Regexp.union(ignore)
+    ignore_bracket_methods, ignore_other_methods = ignore.partition {|i| i.start_with?('[') }
 
-    matching = entries.reject do |entry|
-      entry =~ /^\w*\.?#{ignore}[$\(\s]/ or
-        entry =~ /\s#{ignore}\s/
+    if ignore_other_methods.any?
+      ignore_union = Regexp.union(ignore_other_methods)
+      entries.reject! do |entry|
+        /\A(?:\w*\.)?#{ignore_union}(?:[(\s]|\z)/.match?(entry) ||
+          /\s#{ignore_union}\s/.match?(entry)
+      end
+    end
+    if ignore_bracket_methods.any?
+      entries.reject! do |entry|
+        # Ignore `receiver[arg] -> return_type` `[](arg)` `[]`
+        /\A\w*\[.*?\](?:[(\s]|\z)/.match?(entry)
+      end
     end
 
-    matching.empty? ? nil : matching.join("\n")
+    entries.empty? ? nil : entries.join("\n")
   end
 end

data/lib/rdoc/code_object/class_module.rb

@@ -30,7 +30,22 @@ class RDoc::ClassModule < RDoc::Context
   attr_accessor :constant_aliases
 
   ##
-  # Comment and the location it came from.  Use #add_comment to add comments
+  # An array of `[comment, location]` pairs documenting this class/module.
+  # Use #add_comment to add comments.
+  #
+  # Before marshalling:
+  # - +comment+ is a String
+  # - +location+ is an RDoc::TopLevel
+  #
+  # After unmarshalling:
+  # - +comment+ is an RDoc::Markup::Document
+  # - +location+ is a filename String
+  #
+  # These type changes are acceptable (for now) because:
+  # - +comment+: Both String and Document respond to #empty?, and #parse
+  #   returns Document as-is (see RDoc::Text#parse)
+  # - +location+: Only used by #parse to set Document#file, which accepts
+  #   both TopLevel (extracts relative_name) and String
 
   attr_accessor :comment_location
 
@@ -110,7 +125,7 @@ class RDoc::ClassModule < RDoc::Context
     @is_alias_for     = nil
     @name             = name
     @superclass       = superclass
-    @comment_location = [] # [[comment, location]]
+    @comment_location = [] # Array of [comment, location] pairs
 
     super()
   end
@@ -173,10 +188,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
 
@@ -379,10 +410,10 @@ class RDoc::ClassModule < RDoc::Context
 
     @comment    = RDoc::Comment.from_document document
 
-    @comment_location = if RDoc::Markup::Document === document.parts.first then
-                          document
+    @comment_location = if document.parts.first.is_a?(RDoc::Markup::Document)
+                          document.parts.map { |doc| [doc, doc.file] }
                         else
-                          RDoc::Markup::Document.new document
+                          [[document, document.file]]
                         end
 
     array[5].each do |name, rw, visibility, singleton, file|
@@ -462,7 +493,12 @@ class RDoc::ClassModule < RDoc::Context
       document = document.merge other_document
 
       @comment = RDoc::Comment.from_document(document)
-      @comment_location = document
+
+      @comment_location = if document.parts.first.is_a?(RDoc::Markup::Document)
+                            document.parts.map { |doc| [doc, doc.file] }
+                          else
+                            [[document, document.file]]
+                          end
     end
 
     cm = class_module
@@ -689,6 +725,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
     [
@@ -702,6 +741,16 @@ class RDoc::ClassModule < RDoc::Context
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the first comment for search results.
+
+  def search_snippet
+    first_comment = @comment_location.first&.first
+    return '' unless first_comment && !first_comment.empty?
+
+    snippet(first_comment)
+  end
+
   ##
   # Sets the store for this class or module and its contained code objects.
 
@@ -794,11 +843,13 @@ class RDoc::ClassModule < RDoc::Context
       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
 
       cm_alias.aliases.clear
       cm_alias.is_alias_for = cm

data/lib/rdoc/code_object/constant.rb

@@ -154,6 +154,15 @@ class RDoc::Constant < RDoc::CodeObject
     "#{@parent.path}##{@name}"
   end
 
+  ##
+  # 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

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

@@ -70,11 +70,30 @@ class RDoc::Context::Section
   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]'
 
+    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
 

data/lib/rdoc/code_object/method_attr.rb

@@ -375,6 +375,9 @@ class RDoc::MethodAttr < RDoc::CodeObject
   ##
   # Used by RDoc::Generator::JsonIndex to create a record for the search
   # engine.
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     [
@@ -384,10 +387,19 @@ class RDoc::MethodAttr < RDoc::CodeObject
       @parent.full_name,
       path,
       params,
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   def to_s # :nodoc:
     if @is_alias_for
       "#{self.class.name}: #{full_name} -> #{is_alias_for}"

data/lib/rdoc/code_object/top_level.rb

@@ -16,6 +16,16 @@ class RDoc::TopLevel < RDoc::Context
 
   attr_accessor :absolute_name
 
+  ##
+  # Base name of this file
+
+  attr_reader :base_name
+
+  ##
+  # Base name of this file without the extension
+
+  attr_reader :page_name
+
   ##
   # All the classes or modules that were declared in
   # this file. These are assigned to either +#classes_hash+
@@ -40,6 +50,14 @@ class RDoc::TopLevel < RDoc::Context
     @relative_name = relative_name
     @parser        = nil
 
+    if relative_name
+      @base_name = File.basename(relative_name)
+      @page_name = @base_name.sub(/\.(rb|rdoc|txt|md)\z/i, '')
+    else
+      @base_name = nil
+      @page_name = nil
+    end
+
     @classes_or_modules = []
   end
 
@@ -105,13 +123,6 @@ class RDoc::TopLevel < RDoc::Context
     @classes_or_modules << mod
   end
 
-  ##
-  # Base name of this file
-
-  def base_name
-    File.basename @relative_name
-  end
-
   alias name base_name
 
   ##
@@ -204,16 +215,6 @@ class RDoc::TopLevel < RDoc::Context
     end
   end
 
-  ##
-  # Base name of this file without the extension
-
-  def page_name
-    basename = File.basename @relative_name
-    basename =~ /\.(rb|rdoc|txt|md)$/i
-
-    $` || basename
-  end
-
   ##
   # Path to this file for use with HTML generator output.
 
@@ -236,6 +237,9 @@ class RDoc::TopLevel < 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
     return unless @parser < RDoc::Parser::Text
@@ -247,10 +251,19 @@ class RDoc::TopLevel < RDoc::Context
       '',
       path,
       '',
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   ##
   # Is this TopLevel from a text file instead of a source code file?
 

data/lib/rdoc/comment.rb

@@ -162,6 +162,12 @@ class RDoc::Comment
     self
   end
 
+  # Change normalized, when creating already normalized comment.
+
+  def normalized=(value)
+    @normalized = value
+  end
+
   ##
   # Was this text normalized?
 
@@ -223,14 +229,190 @@ class RDoc::Comment
     @format == 'tomdoc'
   end
 
-  ##
-  # Create a new parsed comment from a document
+  MULTILINE_DIRECTIVES = %w[call-seq].freeze # :nodoc:
 
-  def self.from_document(document) # :nodoc:
-    comment = RDoc::Comment.new('')
-    comment.document = document
-    comment.location = RDoc::TopLevel.new(document.file) if document.file
-    comment
-  end
+  # There are more, but already handled by RDoc::Parser::C
+  COLON_LESS_DIRECTIVES = %w[call-seq Document-method].freeze # :nodoc:
+
+  DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP = /\A(?<colon>\\?:|:?)(?<directive>[\w-]+):(?<param>.*)/
+
+  private_constant :MULTILINE_DIRECTIVES, :COLON_LESS_DIRECTIVES, :DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP
+
+  class << self
+
+    ##
+    # Create a new parsed comment from a document
 
+    def from_document(document) # :nodoc:
+      comment = RDoc::Comment.new('')
+      comment.document = document
+      comment.location = RDoc::TopLevel.new(document.file) if document.file
+      comment
+    end
+
+    # Parse comment, collect directives as an attribute and return [normalized_comment_text, directives_hash]
+    # This method expands include and removes everything not needed in the document text, such as
+    # private section, directive line, comment characters `# /* * */` and indent spaces.
+    #
+    # RDoc comment consists of include, directive, multiline directive, private section and comment text.
+    #
+    # Include
+    #   # :include: filename
+    #
+    # Directive
+    #   # :directive-without-value:
+    #   # :directive-with-value: value
+    #
+    # Multiline directive (only :call-seq:)
+    #   # :multiline-directive:
+    #   #   value1
+    #   #   value2
+    #
+    # Private section
+    #   #--
+    #   # private comment
+    #   #++
+
+    def parse(text, filename, line_no, type, &include_callback)
+      case type
+      when :ruby
+        text = text.gsub(/^#+/, '') if text.start_with?('#')
+        private_start_regexp = /^-{2,}$/
+        private_end_regexp = /^\+{2}$/
+        indent_regexp = /^\s*/
+      when :c
+        private_start_regexp = /^(\s*\*)?-{2,}$/
+        private_end_regexp = /^(\s*\*)?\+{2}$/
+        indent_regexp = /^\s*(\/\*+|\*)?\s*/
+        text = text.gsub(/\s*\*+\/\s*\z/, '')
+      when :simple
+        # Unlike other types, this implementation only looks for two dashes at
+        # the beginning of the line. Three or more dashes are considered to be
+        # a rule and ignored.
+        private_start_regexp = /^-{2}$/
+        private_end_regexp = /^\+{2}$/
+        indent_regexp = /^\s*/
+      end
+
+      directives = {}
+      lines = text.split("\n")
+      in_private = false
+      comment_lines = []
+      until lines.empty?
+        line = lines.shift
+        read_lines = 1
+        if in_private
+          # If `++` appears in a private section that starts with `--`, private section ends.
+          in_private = false if line.match?(private_end_regexp)
+          line_no += read_lines
+          next
+        elsif line.match?(private_start_regexp)
+          # If `--` appears in a line, private section starts.
+          in_private = true
+          line_no += read_lines
+          next
+        end
+
+        prefix = line[indent_regexp]
+        prefix_indent = ' ' * prefix.size
+        line = line.byteslice(prefix.bytesize..)
+
+        if (directive_match = DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP.match(line))
+          colon = directive_match[:colon]
+          directive = directive_match[:directive]
+          raw_param = directive_match[:param]
+          param = raw_param.strip
+        else
+          colon = directive = raw_param = param = nil
+        end
+
+        if !directive
+          comment_lines << prefix_indent + line
+        elsif colon == '\\:'
+          # If directive is escaped, unescape it
+          comment_lines << prefix_indent + line.sub('\\:', ':')
+        elsif raw_param.start_with?(':') || (colon.empty? && !COLON_LESS_DIRECTIVES.include?(directive))
+          # Something like `:toto::` is not a directive
+          # Only few directives allows to start without a colon
+          comment_lines << prefix_indent + line
+        elsif directive == 'include'
+          filename_to_include = param
+          include_callback.call(filename_to_include, prefix_indent).lines.each { |l| comment_lines << l.chomp }
+        elsif MULTILINE_DIRECTIVES.include?(directive)
+          value_lines = take_multiline_directive_value_lines(directive, filename, line_no, lines, prefix_indent.size, indent_regexp, !param.empty?)
+          read_lines += value_lines.size
+          lines.shift(value_lines.size)
+          unless param.empty?
+            # Accept `:call-seq: first-line\n  second-line` for now
+            value_lines.unshift(param)
+          end
+          value = value_lines.join("\n")
+          directives[directive] = [value.empty? ? nil : value, line_no]
+        else
+          directives[directive] = [param.empty? ? nil : param, line_no]
+        end
+        line_no += read_lines
+      end
+
+      normalized_comment = String.new(encoding: text.encoding) << normalize_comment_lines(comment_lines).join("\n")
+      [normalized_comment, directives]
+    end
+
+    # Remove preceding indent spaces and blank lines from the comment lines
+
+    private def normalize_comment_lines(lines)
+      blank_line_regexp = /\A\s*\z/
+      lines = lines.dup
+      lines.shift while lines.first&.match?(blank_line_regexp)
+      lines.pop while lines.last&.match?(blank_line_regexp)
+
+      min_spaces = lines.map do |l|
+        l.match(/\A *(?=\S)/)&.end(0)
+      end.compact.min
+      if min_spaces && min_spaces > 0
+        lines.map { |l| l[min_spaces..] || '' }
+      else
+        lines
+      end
+    end
+
+    # Take value lines of multiline directive
+
+    private def take_multiline_directive_value_lines(directive, filename, line_no, lines, base_indent_size, indent_regexp, has_param)
+      return [] if lines.empty?
+
+      first_indent_size = lines.first.match(indent_regexp).end(0)
+
+      # Blank line or unindented line is not part of multiline-directive value
+      return [] if first_indent_size <= base_indent_size
+
+      if has_param
+        # :multiline-directive: line1
+        #   line2
+        #   line3
+        #
+        value_lines = lines.take_while do |l|
+          l.rstrip.match(indent_regexp).end(0) > base_indent_size
+        end
+        min_indent = value_lines.map { |l| l.match(indent_regexp).end(0) }.min
+        value_lines.map { |l| l[min_indent..] }
+      else
+        # Take indented lines accepting blank lines between them
+        value_lines = lines.take_while do |l|
+          l = l.rstrip
+          indent = l[indent_regexp]
+          if indent == l || indent.size >= first_indent_size
+            true
+          end
+        end
+        value_lines.map! { |l| (l[first_indent_size..] || '').chomp }
+
+        if value_lines.size != lines.size && !value_lines.last.empty?
+          warn "#{filename}:#{line_no} Multiline directive :#{directive}: should end with a blank line."
+        end
+        value_lines.pop while value_lines.last&.empty?
+        value_lines
+      end
+    end
+  end
 end

data/lib/rdoc/cross_reference.rb

@@ -132,47 +132,56 @@ class RDoc::CrossReference
   end
 
   ##
-  # Returns a method reference to +name+.
+  # Returns a method, attribute or constant reference to +name+
+  # if it exists in the containing context object. It returns
+  # nil otherwise.
+  #
+  # For example, this method would decompose name = 'A::CONSTANT' into a
+  # container object A and a symbol 'CONSTANT', and it would try to find
+  # 'CONSTANT' in A.
 
-  def resolve_method(name)
+  def resolve_local_symbol(name)
     ref = nil
+    type = nil
+    container = nil
 
-    if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+    case name
+    when /#{CLASS_REGEXP_STR}::([A-Z]\w*)\z/o then
+      symbol = $2
+      container = @context.find_symbol_module($1)
+    when /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o then
       type = $2
       if '.' == type # will find either #method or ::method
-        method = $3
+        symbol = $3
       else
-        method = "#{type}#{$3}"
+        symbol = "#{type}#{$3}"
       end
       container = @context.find_symbol_module($1)
-    elsif /^([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+    when /^([.#]|::)#{METHOD_REGEXP_STR}/o then
       type = $1
       if '.' == type
-        method = $2
+        symbol = $2
       else
-        method = "#{type}#{$2}"
+        symbol = "#{type}#{$2}"
       end
       container = @context
-    else
-      type = nil
-      container = nil
     end
 
     if container then
       unless RDoc::TopLevel === container then
         if '.' == type then
-          if 'new' == method then # AnyClassName.new will be class method
-            ref = container.find_local_symbol method
-            ref = container.find_ancestor_local_symbol method unless ref
+          if 'new' == symbol then # AnyClassName.new will be class method
+            ref = container.find_local_symbol symbol
+            ref = container.find_ancestor_local_symbol symbol unless ref
           else
-            ref = container.find_local_symbol "::#{method}"
-            ref = container.find_ancestor_local_symbol "::#{method}" unless ref
-            ref = container.find_local_symbol "##{method}" unless ref
-            ref = container.find_ancestor_local_symbol "##{method}" unless ref
+            ref = container.find_local_symbol "::#{symbol}"
+            ref = container.find_ancestor_local_symbol "::#{symbol}" unless ref
+            ref = container.find_local_symbol "##{symbol}" unless ref
+            ref = container.find_ancestor_local_symbol "##{symbol}" unless ref
           end
         else
-          ref = container.find_local_symbol method
-          ref = container.find_ancestor_local_symbol method unless ref
+          ref = container.find_local_symbol symbol
+          ref = container.find_ancestor_local_symbol symbol unless ref
         end
       end
     end
@@ -197,7 +206,7 @@ class RDoc::CrossReference
             @context.find_symbol name
           end
 
-    ref = resolve_method name unless ref
+    ref = resolve_local_symbol name unless ref
 
     # Try a page name
     ref = @store.page name if not ref and name =~ /^[\w.\/]+$/