rdoc 7.0.3 → 7.1.0

data/lib/rdoc/code_object/class_module.rb

@@ -188,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
 
@@ -477,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

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/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.\/]+$/

data/lib/rdoc/generator/template/aliki/class.rhtml

@@ -29,6 +29,7 @@
     </ol>
   <% end %>
 
+  <span id="<%= h klass.legacy_aref %>" class="legacy-anchor"></span>
   <h1 id="<%= h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>
@@ -38,6 +39,7 @@
   </section>
 
   <%- klass.each_section do |section, constants, attributes| %>
+  <span id="<%= section.legacy_aref %>" class="legacy-anchor"></span>
   <section id="<%= section.aref %>" class="documentation-section anchor-link">
     <%- if section.title then %>
     <header class="documentation-section-title">
@@ -157,7 +159,7 @@
             </details>
           </div>
           <div class="method-source-code" id="<%= method.html_name %>-source">
-            <pre class="<%= method.source_language %>" data-language="<%= method.source_language %>"><%= method.markup_code %></pre>
+            <pre class="<%= method.source_language %>"><%= method.markup_code %></pre>
           </div>
         <%- end %>
 

data/lib/rdoc/generator/template/aliki/css/rdoc.css

@@ -1190,6 +1190,26 @@ main .anchor-link:target {
   scroll-margin-top: calc(var(--layout-header-height) + 2rem);
 }
 
+/* Legacy anchor for backward compatibility with old label- prefix links */
+.legacy-anchor {
+  display: block;
+  position: relative;
+  visibility: hidden;
+  scroll-margin-top: calc(var(--layout-header-height) + 2rem);
+}
+
+/* When a legacy anchor is targeted, highlight the next heading sibling */
+.legacy-anchor:target + h1,
+.legacy-anchor:target + h2,
+.legacy-anchor:target + h3,
+.legacy-anchor:target + h4,
+.legacy-anchor:target + h5,
+.legacy-anchor:target + h6 {
+  margin-left: calc(-1 * var(--space-5));
+  padding-left: calc(var(--space-5) / 2);
+  border-left: calc(var(--space-5) / 2) solid var(--color-border-default);
+}
+
 
 /* Utility Classes */
 .hide { display: none !important; }

data/lib/rdoc/generator/template/aliki/js/c_highlighter.js

@@ -276,7 +276,7 @@
    * Initialize C syntax highlighting on page load
    */
   function initHighlighting() {
-    const codeBlocks = document.querySelectorAll('pre[data-language="c"]');
+    const codeBlocks = document.querySelectorAll('pre.c');
 
     codeBlocks.forEach(block => {
       if (block.getAttribute('data-highlighted') === 'true') {

data/lib/rdoc/generator/template/darkfish/class.rhtml

@@ -33,6 +33,7 @@
     </ol>
   <% end %>
 
+  <span id="<%= h klass.legacy_aref %>" class="legacy-anchor"></span>
   <h1 id="<%= h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>
@@ -42,6 +43,7 @@
   </section>
 
   <%- klass.each_section do |section, constants, attributes| %>
+  <span id="<%= section.legacy_aref %>" class="legacy-anchor"></span>
   <section id="<%= section.aref %>" class="documentation-section anchor-link">
     <%- if section.title then %>
     <header class="documentation-section-title">

data/lib/rdoc/generator/template/darkfish/css/rdoc.css

@@ -92,6 +92,25 @@ main .anchor-link:target {
   scroll-margin-top: 1rem;
 }
 
+/* Legacy anchor for backward compatibility with old label- prefix links */
+.legacy-anchor {
+  display: block;
+  position: relative;
+  visibility: hidden;
+  scroll-margin-top: 1rem;
+}
+
+/* When a legacy anchor is targeted, highlight the next heading sibling */
+.legacy-anchor:target + h1,
+.legacy-anchor:target + h2,
+.legacy-anchor:target + h3,
+.legacy-anchor:target + h4,
+.legacy-anchor:target + h5,
+.legacy-anchor:target + h6 {
+  margin-left: -10px;
+  border-left: 10px solid var(--border-color);
+}
+
 /* 4. Links */
 a {
   color: var(--link-color);

data/lib/rdoc/markdown.kpeg

@@ -490,11 +490,7 @@
   # Wraps `text` in strike markup for rdoc inline formatting
 
   def strike text
-    if text =~ /\A[a-z\d.\/-]+\z/i then
-      "~#{text}~"
-    else
-      "<s>#{text}</s>"
-    end
+    "<del>#{text}</del>"
   end
 
   ##

data/lib/rdoc/markdown.rb

@@ -875,11 +875,7 @@ class RDoc::Markdown
   # Wraps `text` in strike markup for rdoc inline formatting
 
   def strike text
-    if text =~ /\A[a-z\d.\/-]+\z/i then
-      "~#{text}~"
-    else
-      "<s>#{text}</s>"
-    end
+    "<del>#{text}</del>"
   end
 
   ##

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/heading.rb

@@ -2,6 +2,33 @@
 
 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
+
     # A heading with a level (1-6) and text
     #
     #  RDoc syntax:
@@ -13,13 +40,8 @@ module RDoc
     #   # Heading 1
     #   ## Heading 2
     #   ### Heading 3
-    class Heading < Element
-      #: String
-      attr_reader :text
-
-      #: Integer
-      attr_accessor :level
-
+    #
+    class Heading
       # A singleton RDoc::Markup::ToLabel formatter for headings.
       #: () -> RDoc::Markup::ToLabel
       def self.to_label
@@ -43,38 +65,88 @@ module RDoc
         end
       end
 
-      #: (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
-
       # @override
       #: (untyped) -> void
       def accept(visitor)
         visitor.accept_heading(self)
       end
 
-      # An HTML-safe anchor reference for this header.
+      # 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
-        "label-#{self.class.to_label.convert text.dup}"
+        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 which will include the label from +context+. This helps keep ids unique in HTML.
+      # 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)
-        label = +""
-        label << "#{context.aref}-" if context&.respond_to?(:aref)
-        label << aref
-        label
+        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.

data/lib/rdoc/markup/to_html.rb

@@ -221,10 +221,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   def accept_verbatim(verbatim)
     text = verbatim.text.rstrip
+    format = verbatim.format
 
     klass = nil
 
-    content = if verbatim.ruby? or parseable? text then
+    # Apply Ruby syntax highlighting if
+    # - explicitly marked as Ruby (via ruby? which accepts :ruby or :rb)
+    # - no format specified but the text is parseable as Ruby
+    # Otherwise, add language class when applicable and skip Ruby highlighting
+    content = if verbatim.ruby? || (format.nil? && parseable?(text))
                 begin
                   tokens = RDoc::Parser::RipperStateLex.parse text
                   klass  = ' class="ruby"'
@@ -236,6 +241,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
                   CGI.escapeHTML text
                 end
               else
+                klass = " class=\"#{format}\"" if format
                 CGI.escapeHTML text
               end
 
@@ -306,6 +312,13 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     level = [6, heading.level].min
 
     label = heading.label @code_object
+    legacy_label = heading.legacy_label @code_object
+
+    # Add legacy anchor before the heading for backward compatibility.
+    # This allows old links with label- prefix to still work.
+    if @options.output_decoration && !@options.pipe
+      @res << "\n<span id=\"#{legacy_label}\" class=\"legacy-anchor\"></span>"
+    end
 
     @res << if @options.output_decoration
               "\n<h#{level} id=\"#{label}\">"
@@ -362,14 +375,18 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Generate a link to +url+ with content +text+.  Handles the special cases
-  # for img: and link: described under handle_regexp_HYPERLINK
+  # Generates an HTML link or image tag for the given +url+ and +text+.
+  #
+  # - Image URLs (http/https/link ending in .gif, .png, .jpg, .jpeg, .bmp)
+  #   become <img> tags
+  # - File references (.rb, .rdoc, .md) are converted to .html paths
+  # - Anchor URLs (#foo) pass through unchanged for GitHub-style header linking
+  # - Footnote links get wrapped in <sup> tags
 
   def gen_url(url, text)
     scheme, url, id = parse_url url
 
-    if %w[http https link].include?(scheme) and
-       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
+    if %w[http https link].include?(scheme) && url =~ /\.(gif|png|jpg|jpeg|bmp)\z/
       "<img src=\"#{url}\" />"
     else
       if scheme != 'link' and %r%\A((?!https?:)(?:[^/#]*/)*+)([^/#]+)\.(rb|rdoc|md)(?=\z|#)%i =~ url
@@ -381,9 +398,11 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
       link = "<a#{id} href=\"#{url}\">#{text}</a>"
 
-      link = "<sup>#{link}</sup>" if /"foot/ =~ id
-
-      link
+      if /"foot/.match?(id)
+        "<sup>#{link}</sup>"
+      else
+        link
+      end
     end
   end
 
@@ -400,9 +419,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # Maps attributes to HTML tags
 
   def init_tags
-    add_tag :BOLD, "<strong>", "</strong>"
-    add_tag :TT,   "<code>",   "</code>"
-    add_tag :EM,   "<em>",     "</em>"
+    add_tag :BOLD,   "<strong>", "</strong>"
+    add_tag :TT,     "<code>",   "</code>"
+    add_tag :EM,     "<em>",     "</em>"
+    add_tag :STRIKE, "<del>",    "</del>"
   end
 
   ##

data/lib/rdoc/markup/to_html_crossref.rb

@@ -169,14 +169,33 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       end
 
       if label
+        # Convert label to GitHub-style anchor format
+        # First convert + to space (URL encoding), then apply GitHub-style rules
+        formatted_label = RDoc::Text.to_anchor(label.tr('+', ' '))
+
+        # Case 1: Path already has an anchor (e.g., method link)
+        #   Input:  C1#method@label -> path="C1.html#method-i-m"
+        #   Output: C1.html#method-i-m-label
         if path =~ /#/
-          path << "-label-#{label}"
-        elsif ref&.sections&.any? { |section| label == section.title }
-          path << "##{label}"
+          path << "-#{formatted_label}"
+
+        # Case 2: Label matches a section title
+        #   Input:  C1@Section -> path="C1.html", section "Section" exists
+        #   Output: C1.html#section (uses section.aref for GitHub-style)
+        elsif (section = ref&.sections&.find { |s| label.tr('+', ' ') == s.title })
+          path << "##{section.aref}"
+
+        # Case 3: Ref has an aref (class/module context)
+        #   Input:  C1@heading -> path="C1.html", ref=C1 class
+        #   Output: C1.html#class-c1-heading
         elsif ref.respond_to?(:aref)
-          path << "##{ref.aref}-label-#{label}"
+          path << "##{ref.aref}-#{formatted_label}"
+
+        # Case 4: No context, just the label (e.g., TopLevel/file)
+        #   Input:  README@section -> path="README_md.html"
+        #   Output: README_md.html#section
         else
-          path << "#label-#{label}"
+          path << "##{formatted_label}"
         end
       end
 

data/lib/rdoc/markup/to_label.rb

@@ -28,11 +28,21 @@ class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
   end
 
   ##
-  # Converts +text+ to an HTML-safe label
+  # Converts +text+ to an HTML-safe label using GitHub-style anchor formatting.
 
   def convert(text)
     label = convert_flow @am.flow text
 
+    RDoc::Text.to_anchor(label)
+  end
+
+  ##
+  # Converts +text+ to an HTML-safe label using legacy RDoc formatting.
+  # Used for generating backward-compatible anchor aliases.
+
+  def convert_legacy(text)
+    label = convert_flow @am.flow text
+
     CGI.escape(label).gsub('%', '-').sub(/^-/, '')
   end
 

data/lib/rdoc/markup/verbatim.rb

@@ -70,7 +70,7 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
 
   def ruby?
     @format ||= nil # TODO for older ri data, switch the tree to marshal_dump
-    @format == :ruby
+    @format == :ruby || @format == :rb
   end
 
   ##