rdoc 7.2.0 → 8.1.0

data/lib/rdoc/comment.rb

@@ -1,417 +1,354 @@
 # frozen_string_literal: true
-##
-# A comment holds the text comment for a RDoc::CodeObject and provides a
-# unified way of cleaning it up and parsing it into an RDoc::Markup::Document.
-#
-# 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 Reference}[rdoc-ref:doc/markup_reference/rdoc.rdoc@Directive+for+Specifying+RDoc+Source+Format].
-
-
-class RDoc::Comment
-
-  include RDoc::Text
-
+module RDoc
   ##
-  # The format of this comment.  Defaults to RDoc::Markup
+  # A comment holds the text comment for a RDoc::CodeObject and provides a
+  # unified way of cleaning it up and parsing it into an RDoc::Markup::Document.
+  #
+  # 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 Reference}[rdoc-ref:doc/markup_reference/rdoc.rdoc@Directive+for+Specifying+RDoc+Source+Format].
 
-  attr_reader :format
 
-  ##
-  # The RDoc::TopLevel this comment was found in
+  class Comment
 
-  attr_accessor :location
+    include Text
 
-  ##
-  # Line where this Comment was written
+    ##
+    # The format of this comment.  Defaults to RDoc::Markup
 
-  attr_accessor :line
+    attr_reader :format
 
-  ##
-  # For duck-typing when merging classes at load time
+    ##
+    # The RDoc::TopLevel this comment was found in
 
-  alias file location # :nodoc:
+    attr_accessor :location
 
-  ##
-  # The text for this comment
+    ##
+    # Line where this Comment was written
 
-  attr_reader :text
+    attr_accessor :line
 
-  ##
-  # Alias for text
+    ##
+    # For duck-typing when merging classes at load time
 
-  alias to_s text
+    alias file location # :nodoc:
 
-  ##
-  # Overrides the content returned by #parse.  Use when there is no #text
-  # source for this comment
+    ##
+    # The text for this comment
 
-  attr_writer   :document
+    attr_reader :text
 
-  ##
-  # Creates a new comment with +text+ that is found in the RDoc::TopLevel
-  # +location+.
+    ##
+    # Alias for text
 
-  def initialize(text = nil, location = nil, language = nil)
-    @location = location
-    @text     = text.nil? ? nil : text.dup
-    @language = language
+    alias to_s text
 
-    @document   = nil
-    @format     = 'rdoc'
-    @normalized = false
-  end
+    ##
+    # Overrides the content returned by #parse.  Use when there is no #text
+    # source for this comment
 
-  ##
-  #--
-  # TODO deep copy @document
+    attr_writer   :document
 
-  def initialize_copy(copy) # :nodoc:
-    @text = copy.text.dup
-  end
+    ##
+    # Creates a new comment with +text+ that is found in the RDoc::TopLevel
+    # +location+.
 
-  def ==(other) # :nodoc:
-    self.class === other and
-      other.text == @text and other.location == @location
-  end
+    def initialize(text = nil, location = nil, language = nil)
+      @location = location
+      @text     = text.nil? ? nil : text.dup
+      @language = language
 
-  ##
-  # 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*/, '')
+      @document   = nil
+      @format     = 'rdoc'
+      @normalized = false
     end
-  end
 
-  ##
-  # A comment is empty if its text String is empty.
+    ##
+    #--
+    # TODO deep copy @document
 
-  def empty?
-    @text.empty? && (@document.nil? || @document.empty?)
-  end
+    def initialize_copy(copy) # :nodoc:
+      @text = copy.text.dup
+    end
 
-  ##
-  # HACK dubious
+    def ==(other) # :nodoc:
+      self.class === other and
+        other.text == @text and other.location == @location
+    end
 
-  def encode!(encoding)
-    @text = String.new @text, encoding: encoding
-    self
-  end
+    ##
+    # A comment is empty if its text String is empty.
 
-  ##
-  # Sets the format of this comment and resets any parsed document
+    def empty?
+      @text.empty? && (@document.nil? || @document.empty?)
+    end
 
-  def format=(format)
-    @format = format
-    @document = nil
-  end
+    ##
+    # HACK dubious
 
-  def inspect # :nodoc:
-    location = @location ? @location.relative_name : '(unknown)'
+    def encode!(encoding)
+      @text = String.new @text, encoding: encoding
+      self
+    end
 
-    "#<%s:%x %s %p>" % [self.class, object_id, location, @text]
-  end
+    ##
+    # Sets the format of this comment and resets any parsed document
 
-  ##
-  # Normalizes the text.  See RDoc::Text#normalize_comment for details
+    def format=(format)
+      @format = format
+      @document = nil
+    end
 
-  def normalize
-    return self unless @text
-    return self if @normalized # TODO eliminate duplicate normalization
+    def inspect # :nodoc:
+      location = @location ? @location.relative_name : '(unknown)'
 
-    @text = normalize_comment @text
+      "#<%s:%x %s %p>" % [self.class, object_id, location, @text]
+    end
 
-    @normalized = true
+    ##
+    # Normalizes the text.  See RDoc::Text#normalize_comment for details
 
-    self
-  end
+    def normalize
+      return self unless @text
+      return self if @normalized # TODO eliminate duplicate normalization
 
-  # Change normalized, when creating already normalized comment.
+      @text = normalize_comment @text
 
-  def normalized=(value)
-    @normalized = value
-  end
+      @normalized = true
 
-  ##
-  # Was this text normalized?
+      self
+    end
 
-  def normalized? # :nodoc:
-    @normalized
-  end
+    # Change normalized, when creating already normalized comment.
 
-  ##
-  # Parses the comment into an RDoc::Markup::Document.  The parsed document is
-  # cached until the text is changed.
+    def normalized=(value)
+      @normalized = value
+    end
 
-  def parse
-    return @document if @document
+    ##
+    # Was this text normalized?
 
-    @document = super @text, @format
-    @document.file = @location
-    @document
-  end
+    def normalized? # :nodoc:
+      @normalized
+    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
+    ##
+    # Parses the comment into an RDoc::Markup::Document.  The parsed document is
+    # cached until the text is changed.
 
-  ##
-  # 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 parse
+      return @document if @document
 
-  def text=(text)
-    raise RDoc::Error, 'replacing document-only comment is not allowed' if
-      @text.nil? and @document
+      @document = super @text, @format
+      @document.file = @location
+      @document
+    end
 
-    @document = nil
-    @text = text.nil? ? nil : text.dup
-  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.
 
-  ##
-  # Returns true if this comment is in TomDoc format.
+    def text=(text)
+      raise Error, 'replacing document-only comment is not allowed' if
+        @text.nil? and @document
 
-  def tomdoc?
-    @format == 'tomdoc'
-  end
+      @document = nil
+      @text = text.nil? ? nil : text.dup
+    end
 
-  MULTILINE_DIRECTIVES = %w[call-seq].freeze # :nodoc:
+    ##
+    # Returns true if this comment is in TomDoc format.
 
-  # There are more, but already handled by RDoc::Parser::C
-  COLON_LESS_DIRECTIVES = %w[call-seq Document-method].freeze # :nodoc:
+    def tomdoc?
+      @format == 'tomdoc'
+    end
 
-  DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP = /\A(?<colon>\\?:|:?)(?<directive>[\w-]+):(?<param>.*)/
+    MULTILINE_DIRECTIVES = %w[call-seq].freeze # :nodoc:
 
-  private_constant :MULTILINE_DIRECTIVES, :COLON_LESS_DIRECTIVES, :DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP
+    # There are more, but already handled by RDoc::Parser::C
+    COLON_LESS_DIRECTIVES = %w[call-seq Document-method].freeze # :nodoc:
 
-  class << self
+    DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP = /\A(?<colon>\\?:|:?)(?<directive>[\w-]+):(?<param>.*)/
 
-    ##
-    # Create a new parsed comment from a document
+    private_constant :MULTILINE_DIRECTIVES, :COLON_LESS_DIRECTIVES, :DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP
 
-    def from_document(document) # :nodoc:
-      comment = RDoc::Comment.new('')
-      comment.document = document
-      comment.location = RDoc::TopLevel.new(document.file) if document.file
-      comment
-    end
+    class << self
 
-    # 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*/
+      ##
+      # Create a new parsed comment from a document
+
+      def from_document(document) # :nodoc:
+        comment = Comment.new('')
+        comment.document = document
+        comment.location = TopLevel.new(document.file) if document.file
+        comment
       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
+      # 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
 
-        prefix = line[indent_regexp]
-        prefix_indent = ' ' * prefix.size
-        line = line.byteslice(prefix.bytesize..)
+        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
 
-        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
+          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)
+          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
-          value = value_lines.join("\n")
-          directives[directive] = [value.empty? ? nil : value, line_no]
-        else
-          directives[directive] = [param.empty? ? nil : param, line_no]
+          line_no += read_lines
         end
-        line_no += read_lines
+
+        normalized_comment = String.new(encoding: text.encoding) << normalize_comment_lines(comment_lines).join("\n")
+        [normalized_comment, directives]
       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
 
-    # 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
+      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
-    end
 
-    # Take value lines of multiline directive
+      # 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?
+      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)
+        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
+        # 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
+        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
-        end
-        value_lines.map! { |l| (l[first_indent_size..] || '').chomp }
+          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."
+          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
-        value_lines.pop while value_lines.last&.empty?
-        value_lines
       end
     end
   end