rdoc 6.15.1 → 7.1.0

data/lib/rdoc/markup/attribute_manager.rb

@@ -89,12 +89,21 @@ class RDoc::Markup::AttributeManager
     add_word_pair "*", "*", :BOLD, true
     add_word_pair "_", "_", :EM, true
     add_word_pair "+", "+", :TT, true
+    add_word_pair "`", "`", :TT, true
 
     add_html "em", :EM, true
     add_html "i",  :EM, true
     add_html "b",  :BOLD, true
     add_html "tt",   :TT, true
     add_html "code", :TT, true
+    add_html "s",   :STRIKE, true
+    add_html "del", :STRIKE, true
+
+    @word_pair_chars = @matching_word_pairs.keys.join
+
+    # Matches a word pair delimiter (*, _, +, `) that is NOT already protected.
+    # Used by #protect_code_markup to escape delimiters inside <code>/<tt> tags.
+    @unprotected_word_pair_regexp = /([#{@word_pair_chars}])(?!#{PROTECT_ATTR})/
   end
 
   ##
@@ -164,7 +173,7 @@ class RDoc::Markup::AttributeManager
     }.keys
     return if tags.empty?
     tags = "[#{tags.join("")}](?!#{PROTECT_ATTR})"
-    all_tags = "[#{@matching_word_pairs.keys.join("")}](?!#{PROTECT_ATTR})"
+    all_tags = "[#{@word_pair_chars}](?!#{PROTECT_ATTR})"
 
     re = /(?:^|\W|#{all_tags})\K(#{tags})(\1*[#\\]?[\w:#{PROTECT_ATTR}.\/\[\]-]+?\S?)\1(?!\1)(?=#{all_tags}|\W|$)/
 
@@ -245,6 +254,23 @@ class RDoc::Markup::AttributeManager
     @str.gsub!(/\\(\\[#{Regexp.escape @protectable.join}])/m, "\\1")
   end
 
+  ##
+  # Protects word pair delimiters (*, _, +) inside
+  # <code> and <tt> tags from being processed as inline formatting.
+  # For example, *bold* in +*bold*+ will NOT be rendered as bold.
+
+  def protect_code_markup
+    @str.gsub!(/<(code|tt)>(.*?)<\/\1>/im) do
+      tag = $1
+      content = $2
+      # Protect word pair delimiters (*, _, +) from being processed
+      escaped = content.gsub(@unprotected_word_pair_regexp, "\\1#{PROTECT_ATTR}")
+      # Protect HTML-like tags from being processed (e.g., <del> inside code)
+      escaped = escaped.gsub(/<(?!#{PROTECT_ATTR})/, "<#{PROTECT_ATTR}")
+      "<#{tag}>#{escaped}</#{tag}>"
+    end
+  end
+
   ##
   # Unescapes regexp handling sequences of text
 
@@ -308,6 +334,7 @@ class RDoc::Markup::AttributeManager
     @str = str.dup
 
     mask_protected_sequences
+    protect_code_markup
 
     @attrs = RDoc::Markup::AttrSpan.new @str.length, @exclusive_bitmap
 

data/lib/rdoc/markup/blank_line.rb

@@ -1,27 +1,29 @@
 # frozen_string_literal: true
-##
-# An empty line.  This class is a singleton.
 
-class RDoc::Markup::BlankLine
-
-  @instance = new
-
-  ##
-  # RDoc::Markup::BlankLine is a singleton
-
-  def self.new
-    @instance
+module RDoc
+  class Markup
+    # An empty line
+    class BlankLine < Element
+      @instance = new
+
+      # RDoc::Markup::BlankLine is a singleton
+      #: () -> BlankLine
+      def self.new
+        @instance
+      end
+
+      # Calls #accept_blank_line on +visitor+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_blank_line(self)
+      end
+
+      # @override
+      #: (PP) -> void
+      def pretty_print(q) # :nodoc:
+        q.text("blankline")
+      end
+    end
   end
-
-  ##
-  # Calls #accept_blank_line on +visitor+
-
-  def accept(visitor)
-    visitor.accept_blank_line self
-  end
-
-  def pretty_print(q) # :nodoc:
-    q.text 'blankline'
-  end
-
 end

data/lib/rdoc/markup/element.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RDoc
+  class Markup
+    # Base class defining the interface for all markup elements found in documentation
+    # @abstract
+    class Element
+      # @abstract
+      #: (untyped) -> void
+      def accept(visitor)
+        raise NotImplementedError, "#{self.class} must implement the accept method"
+      end
+
+      # @abstract
+      #: (PP) -> void
+      def pretty_print(q)
+        raise NotImplementedError, "#{self.class} must implement the pretty_print method"
+      end
+    end
+  end
+end

data/lib/rdoc/markup/hard_break.rb

@@ -1,31 +1,34 @@
 # frozen_string_literal: true
-##
-# A hard-break in the middle of a paragraph.
 
-class RDoc::Markup::HardBreak
-
-  @instance = new
-
-  ##
-  # RDoc::Markup::HardBreak is a singleton
-
-  def self.new
-    @instance
-  end
-
-  ##
-  # Calls #accept_hard_break on +visitor+
-
-  def accept(visitor)
-    visitor.accept_hard_break self
+module RDoc
+  class Markup
+    # A hard-break in the middle of a paragraph.
+    class HardBreak < Element
+      @instance = new
+
+      # RDoc::Markup::HardBreak is a singleton
+      #: () -> HardBreak
+      def self.new
+        @instance
+      end
+
+      # Calls #accept_hard_break on +visitor+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_hard_break(self)
+      end
+
+      #: (top) -> bool
+      def ==(other) # :nodoc:
+        self.class === other
+      end
+
+      # @override
+      #: (PP) -> void
+      def pretty_print(q) # :nodoc:
+        q.text("[break]")
+      end
+    end
   end
-
-  def ==(other) # :nodoc:
-    self.class === other
-  end
-
-  def pretty_print(q) # :nodoc:
-    q.text "[break]"
-  end
-
 end

data/lib/rdoc/markup/heading.rb

@@ -1,84 +1,173 @@
 # frozen_string_literal: true
-##
-# A heading with a level (1-6) and text
 
-RDoc::Markup::Heading =
-  Struct.new :level, :text do
-
-  @to_html = nil
-  @to_label = nil
-
-  ##
-  # A singleton RDoc::Markup::ToLabel formatter for headings.
-
-  def self.to_label
-    @to_label ||= RDoc::Markup::ToLabel.new
-  end
-
-  ##
-  # A singleton plain HTML formatter for headings.  Used for creating labels
-  # for the Table of Contents
-
-  def self.to_html
-    return @to_html if @to_html
-
-    markup = RDoc::Markup.new
-    markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
-
-    @to_html = RDoc::Markup::ToHtml.new nil
-
-    def @to_html.handle_regexp_CROSSREF(target)
-      target.text.sub(/^\\/, '')
+module RDoc
+  class Markup
+    # IMPORTANT! This weird workaround is required to ensure that RDoc can correctly deserializing Marshal data from
+    # older rubies. Older rubies have `Heading` as a struct, so if we change it to a class, deserialization fails
+    if RUBY_VERSION.start_with?("4.")
+      class Heading < Element
+        #: String
+        attr_reader :text
+
+        #: Integer
+        attr_accessor :level
+
+        #: (Integer, String) -> void
+        def initialize(level, text)
+          super()
+
+          @level = level
+          @text = text
+        end
+
+        #: (Object) -> bool
+        def ==(other)
+          other.is_a?(Heading) && other.level == @level && other.text == @text
+        end
+      end
+    else
+      Heading = Struct.new(:level, :text)
     end
 
-    @to_html
-  end
-
-  ##
-  # Calls #accept_heading on +visitor+
-
-  def accept(visitor)
-    visitor.accept_heading self
-  end
-
-  ##
-  # An HTML-safe anchor reference for this header.
-
-  def aref
-    "label-#{self.class.to_label.convert text.dup}"
-  end
-
-  ##
-  # Creates a fully-qualified label which will include the label from
-  # +context+.  This helps keep ids unique in HTML.
-
-  def label(context = nil)
-    label = aref
-
-    label = [context.aref, label].compact.join '-' if
-      context and context.respond_to? :aref
-
-    label
-  end
-
-  ##
-  # HTML markup of the text of this label without the surrounding header
-  # element.
-
-  def plain_html
-    text = self.text.dup
-
-    if matched = text.match(/rdoc-image:[^:]+:(.*)/)
-      text = matched[1]
+    # A heading with a level (1-6) and text
+    #
+    #  RDoc syntax:
+    #   = Heading 1
+    #   == Heading 2
+    #   === Heading 3
+    #
+    #  Markdown syntax:
+    #   # Heading 1
+    #   ## Heading 2
+    #   ### Heading 3
+    #
+    class Heading
+      # A singleton RDoc::Markup::ToLabel formatter for headings.
+      #: () -> RDoc::Markup::ToLabel
+      def self.to_label
+        @to_label ||= Markup::ToLabel.new
+      end
+
+      # A singleton plain HTML formatter for headings. Used for creating labels for the Table of Contents
+      #: () -> RDoc::Markup::ToHtml
+      def self.to_html
+        @to_html ||= begin
+          markup = Markup.new
+          markup.add_regexp_handling CrossReference::CROSSREF_REGEXP, :CROSSREF
+
+          to_html = Markup::ToHtml.new nil
+
+          def to_html.handle_regexp_CROSSREF(target)
+            target.text.sub(/^\\/, '')
+          end
+
+          to_html
+        end
+      end
+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_heading(self)
+      end
+
+      # An HTML-safe anchor reference for this header using GitHub-style formatting:
+      # - Lowercase
+      # - Spaces converted to hyphens
+      # - Special characters removed (except hyphens)
+      #
+      # Examples:
+      #   "Hello"       -> "hello"
+      #   "Hello World" -> "hello-world"
+      #   "Foo Bar Baz" -> "foo-bar-baz"
+      #
+      #: () -> String
+      def aref
+        self.class.to_label.convert text.dup
+      end
+
+      # An HTML-safe anchor reference using legacy RDoc formatting:
+      # - Prefixed with "label-"
+      # - Original case preserved
+      # - Spaces converted to + (URL encoding style)
+      # - Special characters percent-encoded
+      #
+      # Returns nil if it would be the same as the GitHub-style aref (no alias needed).
+      #
+      # Examples:
+      #   "hello"       -> "label-hello" (different due to label- prefix)
+      #   "Hello"       -> "label-Hello"
+      #   "Hello World" -> "label-Hello+World"
+      #   "Foo Bar Baz" -> "label-Foo+Bar+Baz"
+      #
+      #: () -> String?
+      def legacy_aref
+        "label-#{self.class.to_label.convert_legacy text.dup}"
+      end
+
+      # Creates a fully-qualified label (GitHub-style) which includes the context's aref prefix.
+      # This helps keep IDs unique in HTML when headings appear within class/method documentation.
+      #
+      # Examples (without context):
+      #   "Hello World" -> "hello-world"
+      #
+      # Examples (with context being class Foo):
+      #   "Hello World" -> "class-foo-hello-world"
+      #
+      # Examples (with context being method #bar):
+      #   "Hello World" -> "method-i-bar-hello-world"
+      #
+      #: (RDoc::Context?) -> String
+      def label(context = nil)
+        result = +""
+        result << "#{context.aref}-" if context&.respond_to?(:aref)
+        result << aref
+        result
+      end
+
+      # Creates a fully-qualified legacy label for backward compatibility.
+      # This is used to generate a secondary ID attribute on the heading's inner anchor,
+      # allowing old-style links (e.g., #label-Hello+World) to continue working.
+      #
+      # Examples (without context):
+      #   "hello"       -> "label-hello"
+      #   "Hello World" -> "label-Hello+World"
+      #
+      # Examples (with context being class Foo):
+      #   "hello"       -> "class-Foo-label-hello"
+      #   "Hello World" -> "class-Foo-label-Hello+World"
+      #
+      #: (RDoc::Context?) -> String
+      def legacy_label(context = nil)
+        result = +""
+        if context&.respond_to?(:legacy_aref)
+          result << "#{context.legacy_aref}-"
+        elsif context&.respond_to?(:aref)
+          result << "#{context.aref}-"
+        end
+        result << legacy_aref
+        result
+      end
+
+      # HTML markup of the text of this label without the surrounding header element.
+      #: () -> String
+      def plain_html
+        no_image_text = text
+
+        if matched = no_image_text.match(/rdoc-image:[^:]+:(.*)/)
+          no_image_text = matched[1]
+        end
+
+        self.class.to_html.to_html(no_image_text)
+      end
+
+      # @override
+      #: (PP) -> void
+      def pretty_print(q)
+        q.group 2, "[head: #{level} ", ']' do
+          q.pp text
+        end
+      end
     end
-
-    self.class.to_html.to_html(text)
   end
-
-  def pretty_print(q) # :nodoc:
-    q.group 2, "[head: #{level} ", ']' do
-      q.pp text
-    end
-  end
-
 end

data/lib/rdoc/markup/pre_process.rb

@@ -97,18 +97,15 @@ class RDoc::Markup::PreProcess
   # RDoc::CodeObject#metadata for details.
 
   def handle(text, code_object = nil, &block)
-    first_line = 1
     if RDoc::Comment === text then
       comment = text
       text = text.text
-      first_line = comment.line || 1
     end
 
     # regexp helper (square brackets for optional)
     # $1      $2  $3        $4      $5
     # [prefix][\]:directive:[spaces][param]newline
-    text = text.lines.map.with_index(first_line) do |line, num|
-      next line unless line =~ /\A([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):([\w-]+):([ \t]*)(.+)?(\r?\n|$)/
+    text = text.gsub(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):([\w-]+):([ \t]*)(.+)?(\r?\n|$)/) do
       # skip something like ':toto::'
       next $& if $4.empty? and $5 and $5[0, 1] == ':'
 
@@ -122,9 +119,8 @@ class RDoc::Markup::PreProcess
         comment.format = $5.downcase
         next "#{$1.strip}\n"
       end
-
-      handle_directive $1, $3, $5, code_object, text.encoding, num, &block
-    end.join
+      handle_directive $1, $3, $5, code_object, text.encoding, &block
+    end
 
     if comment then
       comment.text = text
@@ -132,11 +128,39 @@ class RDoc::Markup::PreProcess
       comment = text
     end
 
+    run_post_processes(comment, code_object)
+
+    text
+  end
+
+  # Apply directives to a code object
+
+  def run_pre_processes(comment_text, code_object, start_line_no, type)
+    comment_text, directives = parse_comment(comment_text, start_line_no, type)
+    directives.each do |directive, (param, line_no)|
+      handle_directive('', directive, param, code_object)
+    end
+    if code_object.is_a?(RDoc::AnyMethod) && (call_seq, = directives['call-seq']) && call_seq
+      code_object.call_seq = call_seq.lines.map(&:chomp).reject(&:empty?).join("\n")
+    end
+    format, = directives['markup']
+    [comment_text, format]
+  end
+
+  # Perform post preocesses to a code object
+
+  def run_post_processes(comment, code_object)
     self.class.post_processors.each do |handler|
       handler.call comment, code_object
     end
+  end
 
-    text
+  # Parse comment and return [normalized_comment_text, directives_hash]
+
+  def parse_comment(text, line_no, type)
+    RDoc::Comment.parse(text, @input_file_name, line_no, type) do |filename, prefix_indent|
+      include_file(filename, prefix_indent, text.encoding)
+    end
   end
 
   ##
@@ -151,7 +175,7 @@ class RDoc::Markup::PreProcess
   # When 1.8.7 support is ditched prefix can be defaulted to ''
 
   def handle_directive(prefix, directive, param, code_object = nil,
-                       encoding = nil, line = nil)
+                       encoding = nil)
     blankline = "#{prefix.strip}\n"
     directive = directive.downcase
 
@@ -244,7 +268,7 @@ class RDoc::Markup::PreProcess
 
       blankline
     else
-      result = yield directive, param, line if block_given?
+      result = yield directive, param if block_given?
 
       case result
       when nil then

data/lib/rdoc/markup/raw.rb

@@ -1,69 +1,66 @@
 # frozen_string_literal: true
-##
-# A section of text that is added to the output document as-is
 
-class RDoc::Markup::Raw
-
-  ##
-  # The component parts of the list
-
-  attr_reader :parts
-
-  ##
-  # Creates a new Raw containing +parts+
-
-  def initialize *parts
-    @parts = []
-    @parts.concat parts
-  end
-
-  ##
-  # Appends +text+
+module RDoc
+  class Markup
+    # A section of text that is added to the output document as-is
+    class Raw
+      # The component parts of the list
+      #: Array[String]
+      attr_reader :parts
+
+      # Creates a new Raw containing +parts+
+      #: (*String) -> void
+      def initialize(*parts)
+        @parts = parts
+      end
 
-  def <<(text)
-    @parts << text
-  end
+      # Appends +text+
+      #: (String) -> void
+      def <<(text)
+        @parts << text
+      end
 
-  def ==(other) # :nodoc:
-    self.class == other.class and @parts == other.parts
-  end
+      #: (top) -> bool
+      def ==(other) # :nodoc:
+        self.class == other.class && @parts == other.parts
+      end
 
-  ##
-  # Calls #accept_raw+ on +visitor+
+      # Calls #accept_raw+ on +visitor+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_raw(self)
+      end
 
-  def accept(visitor)
-    visitor.accept_raw self
-  end
+      # Appends +other+'s parts
+      #: (Raw) -> void
+      def merge(other)
+        @parts.concat(other.parts)
+      end
 
-  ##
-  # Appends +other+'s parts
+      # @override
+      #: (PP) -> void
+      def pretty_print(q) # :nodoc:
+        self.class.name =~ /.*::(\w{1,4})/i
 
-  def merge(other)
-    @parts.concat other.parts
-  end
+        q.group(2, "[#{$1.downcase}: ", ']') do
+          q.seplist(@parts) do |part|
+            q.pp(part)
+          end
+        end
+      end
 
-  def pretty_print(q) # :nodoc:
-    self.class.name =~ /.*::(\w{1,4})/i
+      # Appends +texts+ onto this Paragraph
+      #: (*String) -> void
+      def push(*texts)
+        self.parts.concat(texts)
+      end
 
-    q.group 2, "[#{$1.downcase}: ", ']' do
-      q.seplist @parts do |part|
-        q.pp part
+      # The raw text
+      #: () -> String
+      def text
+        @parts.join(" ")
       end
     end
   end
-
-  ##
-  # Appends +texts+ onto this Paragraph
-
-  def push *texts
-    self.parts.concat texts
-  end
-
-  ##
-  # The raw text
-
-  def text
-    @parts.join ' '
-  end
-
 end