rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/code_objects.rb

@@ -2,5 +2,4 @@
 # This file was used to load all the RDoc::CodeObject subclasses at once.  Now
 # autoload handles this.
 
-require 'rdoc'
-
+require_relative '../rdoc'

data/lib/rdoc/comment.rb

@@ -6,8 +6,8 @@
 # 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::Markup@Other+directives for instructions on adding an alternate
-# format.
+# See {RDoc Markup Reference}[rdoc-ref:doc/markup_reference/rdoc.rdoc@Directive+for+Specifying+RDoc+Source+Format].
+
 
 class RDoc::Comment
 
@@ -53,7 +53,7 @@ class RDoc::Comment
   # Creates a new comment with +text+ that is found in the RDoc::TopLevel
   # +location+.
 
-  def initialize text = nil, location = nil, language = nil
+  def initialize(text = nil, location = nil, language = nil)
     @location = location
     @text     = text.nil? ? nil : text.dup
     @language = language
@@ -67,101 +67,34 @@ class RDoc::Comment
   #--
   # TODO deep copy @document
 
-  def initialize_copy copy # :nodoc:
+  def initialize_copy(copy) # :nodoc:
     @text = copy.text.dup
   end
 
-  def == other # :nodoc:
+  def ==(other) # :nodoc:
     self.class === other and
       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 method
-    # 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 @text =~ /^\s*:?call-seq:(.*?(?:\S).*?)^\s*$/m then
-      all_start, all_stop = $~.offset(0)
-      seq_start, seq_stop = $~.offset(1)
-
-      # we get the following lines that start with the leading word at the
-      # same indent, even if they have blank lines before
-      if $1 =~ /(^\s*\n)+^(\s*\w+)/m then
-        leading = $2 # ' *    ARGF' in the example above
-        re = %r%
-          \A(
-             (^\s*\n)+
-             (^#{Regexp.escape leading}.*?\n)+
-            )+
-          ^\s*$
-        %xm
-
-        if @text[seq_stop..-1] =~ re then
-          all_stop = seq_stop + $~.offset(0).last
-          seq_stop = seq_stop + $~.offset(1).last
-        end
-      end
-
-      seq = @text[seq_start..seq_stop]
-      seq.gsub!(/^\s*(\S|\n)/m, '\1')
-      @text.slice! all_start...all_stop
-
-      method.call_seq = seq.chomp
-
-    else
-      regexp = /^\s*:?call-seq:(.*?)(^\s*$|\z)/m
-      if regexp =~ @text then
-        @text = @text.sub(regexp, '')
-        seq = $1
-        seq.gsub!(/^\s*/, '')
-        method.call_seq = seq
-      end
-    end
-
-    method
-  end
-
   ##
   # A comment is empty if its text String is empty.
 
   def empty?
-    @text.empty?
+    @text.empty? && (@document.nil? || @document.empty?)
   end
 
   ##
   # HACK dubious
 
-  def encode! encoding
-    # TODO: Remove this condition after Ruby 2.2 EOL
-    if RUBY_VERSION < '2.3.0'
-      @text = @text.force_encoding encoding
-    else
-      @text = String.new @text, encoding: encoding
-    end
+  def encode!(encoding)
+    @text = String.new @text, encoding: encoding
     self
   end
 
   ##
   # Sets the format of this comment and resets any parsed document
 
-  def format= format
+  def format=(format)
     @format = format
     @document = nil
   end
@@ -186,6 +119,12 @@ class RDoc::Comment
     self
   end
 
+  # Change normalized, when creating already normalized comment.
+
+  def normalized=(value)
+    @normalized = value
+  end
+
   ##
   # Was this text normalized?
 
@@ -205,34 +144,12 @@ 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.
   #
   # An error is raised if the comment contains a document but no text.
 
-  def text= text
+  def text=(text)
     raise RDoc::Error, 'replacing document-only comment is not allowed' if
       @text.nil? and @document
 
@@ -247,4 +164,190 @@ class RDoc::Comment
     @format == 'tomdoc'
   end
 
+  MULTILINE_DIRECTIVES = %w[call-seq].freeze # :nodoc:
+
+  # 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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 ##
 # RDoc::CrossReference is a reusable way to create cross references for names.
 
@@ -14,12 +15,25 @@ class RDoc::CrossReference
 
   CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
 
+  ##
+  # Regular expression to match a single method argument.
+
+  METHOD_ARG_REGEXP_STR = '[\w.+*/=<>-]+'
+
+  ##
+  # Regular expression to match method arguments.
+
+  METHOD_ARGS_REGEXP_STR = /(?:\((?:#{METHOD_ARG_REGEXP_STR}(?:,\s*#{METHOD_ARG_REGEXP_STR})*)?\))?/.source
+
   ##
   # Regular expression to match method references.
   #
   # See CLASS_REGEXP_STR
 
-  METHOD_REGEXP_STR = '([a-z]\w*[!?=]?|%|===|\[\]=?|<<|>>|\+@|-@|-|\+|\*)(?:\([\w.+*/=<>-]*\))?'
+  METHOD_REGEXP_STR = /(
+    (?!\d)[\w]+[!?=]?|
+    %|=(?:==?|~)|![=~]|\[\]=?|<(?:<|=>?)?|>[>=]?|[-+!]@?|\*\*?|[\/%\`|&^~]
+  )#{METHOD_ARGS_REGEXP_STR}/.source.delete("\n ").freeze
 
   ##
   # Regular expressions matching text that should potentially have
@@ -34,12 +48,6 @@ class RDoc::CrossReference
                        # A::B::C.meth
                        #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
 
-                       # Stand-alone method (preceded by a #)
-                       | \\?\##{METHOD_REGEXP_STR}
-
-                       # Stand-alone method (preceded by ::)
-                       | ::#{METHOD_REGEXP_STR}
-
                        # A::B::C
                        # The stuff after CLASS_REGEXP_STR is a
                        # nasty hack.  CLASS_REGEXP_STR unfortunately matches
@@ -56,6 +64,12 @@ class RDoc::CrossReference
                        # marker.
                        | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
 
+                       # Stand-alone method (preceded by a #)
+                       | \\?\##{METHOD_REGEXP_STR}
+
+                       # Stand-alone method (preceded by ::)
+                       | ::#{METHOD_REGEXP_STR}
+
                        # Things that look like filenames
                        # The key thing is that there must be at least
                        # one special character (period, slash, or
@@ -82,12 +96,12 @@ class RDoc::CrossReference
                        # A::B::C.meth
                        #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
 
-                       # Stand-alone method
-                       | \\?#{METHOD_REGEXP_STR}
-
                        # A::B::C
                        | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
 
+                       # Stand-alone method
+                       | \\?#{METHOD_REGEXP_STR}
+
                        # Things that look like filenames
                        | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
 
@@ -108,7 +122,7 @@ class RDoc::CrossReference
   # Allows cross-references to be created based on the given +context+
   # (RDoc::Context).
 
-  def initialize context
+  def initialize(context)
     @context = context
     @store   = context.store
 
@@ -116,87 +130,86 @@ class RDoc::CrossReference
   end
 
   ##
-  # Returns a reference to +name+.
+  # Returns a method, attribute or constant reference to +name+
+  # if it exists in the containing context object. It returns
+  # nil otherwise.
   #
-  # 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.
-
-  def resolve name, text
-    return @seen[name] if @seen.include? name
-
-    if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+  # 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_local_symbol(name)
+    ref = nil
+    type = nil
+    container = nil
+
+    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
 
-    ref = case name
-          when /^\\(#{CLASS_REGEXP_STR})$/o then
-            @context.find_symbol $1
-          else
-            @context.find_symbol name
-          end unless ref
+    ref
+  end
+
+  ##
+  # Returns a reference to +name+.
+  #
+  # 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)
+    return @seen[name] if @seen.include? name
+
+    ref = @context.find_symbol name
+
+    ref = resolve_local_symbol name unless ref
 
     # Try a page name
-    ref = @store.page name if not ref and name =~ /^[\w.]+$/
+    ref = @store.page name if not ref and name =~ /^[\w.\/]+$/
 
     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
     )+
@@ -29,7 +29,7 @@ module RDoc::Encoding
   # If +force_transcode+ is true the document will be transcoded and any
   # unknown character in the target encoding will be replaced with '?'
 
-  def self.read_file filename, encoding, force_transcode = false
+  def self.read_file(filename, encoding, force_transcode = false)
     content = File.open filename, "rb" do |f| f.read end
     content.gsub!("\r\n", "\n") if RUBY_PLATFORM =~ /mswin|mingw/
 
@@ -86,21 +86,10 @@ module RDoc::Encoding
     nil
   end
 
-  def self.remove_frozen_string_literal string
-    string =~ /\A(?:#!.*\n)?(.*\n)/
-    first_line = $1
-
-    if first_line =~ /\A# +frozen[-_]string[-_]literal[=:].+$/i
-      string = string.sub first_line, ''
-    end
-
-    string
-  end
-
   ##
   # Detects the encoding of +string+ based on the magic comment
 
-  def self.detect_encoding string
+  def self.detect_encoding(string)
     result = HEADER_REGEXP.match string
     name = result && result[:name]
 
@@ -110,7 +99,7 @@ module RDoc::Encoding
   ##
   # Removes magic comments and shebang
 
-  def self.remove_magic_comment string
+  def self.remove_magic_comment(string)
     string.sub HEADER_REGEXP do |s|
       s.gsub(/[^\n]/, '')
     end
@@ -120,16 +109,11 @@ module RDoc::Encoding
   # Changes encoding based on +encoding+ without converting and returns new
   # string
 
-  def self.change_encoding text, encoding
+  def self.change_encoding(text, encoding)
     if text.kind_of? RDoc::Comment
       text.encode! encoding
     else
-      # TODO: Remove this condition after Ruby 2.2 EOL
-      if RUBY_VERSION < '2.3.0'
-        text.force_encoding encoding
-      else
-        String.new text, encoding: encoding
-      end
+      String.new text, encoding: encoding
     end
   end
 

data/lib/rdoc/erb_partial.rb

@@ -9,11 +9,10 @@ class RDoc::ERBPartial < ERB
   # Overrides +compiler+ startup to set the +eoutvar+ to an empty string only
   # if it isn't already set.
 
-  def set_eoutvar compiler, eoutvar = '_erbout'
+  def set_eoutvar(compiler, eoutvar = '_erbout')
     super
 
     compiler.pre_cmd = ["#{eoutvar} ||= +''"]
   end
 
 end
-