rdoc 7.0.4 → 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/darkfish.rb

@@ -173,7 +173,7 @@ class RDoc::Generator::Darkfish
   ##
   # Output progress information if debugging is enabled
 
-  def debug_msg(*msg)
+  def debug_msg *msg
     return unless $DEBUG_RDOC
     $stderr.puts(*msg)
   end

data/lib/rdoc/generator/json_index.rb

@@ -118,7 +118,7 @@ class RDoc::Generator::JsonIndex
   ##
   # Output progress information if debugging is enabled
 
-  def debug_msg(*msg)
+  def debug_msg *msg
     return unless $DEBUG_RDOC
     $stderr.puts(*msg)
   end

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

@@ -28,7 +28,7 @@
 <%- elsif @title %>
   <meta name="keywords" content="ruby,documentation,<%= h @title %>">
   <%- if @options.main_page and
-      main_page = @files.find { |f| f.full_name == @options.main_page } %>
+      main_page = @files.find { |f| f.full_name == @options.main_page } then %>
     <meta
       name="description"
       content="<%= h "#{@title}: #{excerpt(main_page.comment)}" %>"

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

@@ -1,4 +1,4 @@
-<%- unless klass.extends.empty? %>
+<%- unless klass.extends.empty? then %>
 <div id="extends-section" class="nav-section">
   <details class="nav-section-collapsible" open>
     <summary class="nav-section-header">
@@ -13,13 +13,11 @@
 
     <ul class="nav-list">
       <%- klass.extends.each do |ext| %>
-      <li>
-      <%- unless String === ext.module %>
-        <a class="extend" href="<%= klass.aref_to ext.module.path %>"><%= ext.module.full_name %></a>
-      <%- else %>
-        <span class="extend"><%= ext.name %></span>
-      <%- end %>
-      </li>
+    <%- unless String === ext.module then %>
+      <li><a class="extend" href="<%= klass.aref_to ext.module.path %>"><%= ext.module.full_name %></a></li>
+    <%- else %>
+      <li><span class="extend"><%= ext.name %></span></li>
+    <%- end %>
     <%- end %>
     </ul>
   </details>

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

@@ -1,4 +1,4 @@
-<%- unless klass.includes.empty? %>
+<%- unless klass.includes.empty? then %>
 <div id="includes-section" class="nav-section">
   <details class="nav-section-collapsible" open>
     <summary class="nav-section-header">
@@ -13,13 +13,11 @@
 
     <ul class="nav-list">
     <%- klass.includes.each do |inc| %>
-      <li>
-      <%- unless String === inc.module %>
-        <a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a>
-      <%- else %>
-        <span class="include"><%= inc.name %></span>
-      <%- end %>
-      </li>
+    <%- unless String === inc.module then %>
+      <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a></li>
+    <%- else %>
+      <li><span class="include"><%= inc.name %></span></li>
+    <%- end %>
     <%- end %>
     </ul>
   </details>

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

@@ -5,7 +5,7 @@
   <%- installed.each do |name, href, exists, type, _| %>
     <%- next if type == :extra %>
     <li class="folder">
-    <%- if exists %>
+    <%- if exists then %>
       <a href="<%= href %>"><%= h name %></a>
     <%- else %>
       <%= h name %>

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

@@ -4,7 +4,7 @@
   <%- dir = current.full_name[%r{\A[^/]+(?=/)}] || current.page_name %>
 <%- end %>
 
-<%- unless simple_files.empty? %>
+<%- unless simple_files.empty? then %>
   <div id="fileindex-section" class="nav-section">
     <details class="nav-section-collapsible" <%= 'open' unless @inside_class_file %>>
       <summary class="nav-section-header">

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

@@ -1,4 +1,4 @@
-<%- unless klass.sections.length == 1 %>
+<%- unless klass.sections.length == 1 then %>
 <div id="sections-section" class="nav-section">
   <details class="nav-section-collapsible" open>
     <summary class="nav-section-header">

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

@@ -22,13 +22,14 @@
         <% if namespace[:self] %>
         <span><%= namespace[:name] %></span>
         <% else %>
-        <a href="<%= namespace[:path] %>"><%= namespace[:name] %></a><span class="separator">::</span>
+        <a href="<%= namespace[:path] %>"><%= namespace[:name] %></a><span>::</span>
         <% end %>
       </li>
       <% end %>
     </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,8 +39,9 @@
   </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 %>
+    <%- if section.title then %>
     <header class="documentation-section-title">
       <h2>
         <a href="#<%= section.aref %>"><%= section.title %></a>
@@ -47,13 +49,13 @@
     </header>
     <%- end %>
 
-    <%- if section.comment %>
+    <%- if section.comment then %>
     <div>
       <%= section.description %>
     </div>
     <%- end %>
 
-    <%- unless constants.empty? %>
+    <%- unless constants.empty? then %>
     <section class="constants-list">
       <header>
         <h3 id="constants"><a href="#constants">Constants</a></h3>
@@ -61,9 +63,9 @@
       <dl>
       <%- constants.each do |const| %>
         <dt id="<%= const.name %>"><%= const.name %></dt>
-        <%- if const.comment %>
+        <%- if const.comment then %>
         <dd>
-          <%- if const.mixin_from %>
+          <%- if const.mixin_from then %>
             <div class="mixin-from">
               Included from <a href="<%= klass.aref_to(const.mixin_from.path) %>"><%= const.mixin_from.full_name %></a>
             </div>
@@ -78,7 +80,7 @@
     </section>
     <%- end %>
 
-    <%- unless attributes.empty? %>
+    <%- unless attributes.empty? then %>
     <section class="attribute-method-details method-section">
       <header>
         <h3 id="attributes"><a href="#attributes">Attributes</a></h3>
@@ -94,12 +96,12 @@
         </div>
 
         <div class="method-description">
-        <%- if attrib.mixin_from %>
+        <%- if attrib.mixin_from then %>
           <div class="mixin-from">
             <%= attrib.singleton ? "Extended" : "Included" %> from <a href="<%= klass.aref_to(attrib.mixin_from.path) %>"><%= attrib.mixin_from.full_name %></a>
           </div>
         <%- end %>
-        <%- if attrib.comment %>
+        <%- if attrib.comment then %>
         <%= attrib.description.strip %>
         <%- else %>
         <p class="missing-docs">(Not documented)</p>
@@ -122,7 +124,7 @@
     <%- methods.each do |method| %>
       <div id="<%= method.aref %>" class="method-detail anchor-link <%= method.is_alias_for ? "method-alias" : '' %>">
         <div class="method-header">
-          <%- if (call_seq = method.call_seq) %>
+          <%- if (call_seq = method.call_seq) then %>
             <%- call_seq.strip.split("\n").each_with_index do |call_seq, i| %>
               <div class="method-heading">
                 <a href="#<%= method.aref %>" title="Link to this method">
@@ -134,7 +136,7 @@
                 </a>
               </div>
             <%- end %>
-          <%- elsif method.has_call_seq? %>
+          <%- elsif method.has_call_seq? then %>
             <div class="method-heading">
               <a href="#<%= method.aref %>" title="Link to this method">
                 <span class="method-name"><%= h method.name %></span>
@@ -157,23 +159,23 @@
             </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 %>
 
-        <%- unless method.skip_description? %>
+        <%- unless method.skip_description? then %>
         <div class="method-description">
-          <%- if method.mixin_from %>
+          <%- if method.mixin_from then %>
             <div class="mixin-from">
               <%= method.singleton ? "Extended" : "Included" %> from <a href="<%= klass.aref_to(method.mixin_from.path) %>"><%= method.mixin_from.full_name %></a>
             </div>
           <%- end %>
-          <%- if method.comment %>
+          <%- if method.comment then %>
           <%= method.description.strip %>
           <%- else %>
           <p class="missing-docs">(Not documented)</p>
           <%- end %>
-          <%- if method.calls_super %>
+          <%- if method.calls_super then %>
             <div class="method-calls-super">
               Calls superclass method
               <%=
@@ -185,7 +187,7 @@
         </div>
         <%- end %>
 
-        <%- unless method.aliases.empty? %>
+        <%- unless method.aliases.empty? then %>
         <div class="aliases">
           Also aliased as: <%= method.aliases.map do |aka|
             if aka.parent then # HACK lib/rexml/encodings
@@ -197,7 +199,7 @@
         </div>
         <%- end %>
 
-        <%- if method.is_alias_for %>
+        <%- if method.is_alias_for then %>
         <div class="aliases">
           Alias for: <a href="<%= klass.aref_to method.is_alias_for.path %>"><%= h method.is_alias_for.name %></a>
         </div>

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/aliki/servlet_root.rhtml

@@ -42,7 +42,7 @@
 
 <%- gems = installed.select { |_, _, _, type,| type == :gem } %>
 <%- missing = gems.reject { |_, _, exists,| exists } %>
-<%- unless missing.empty? %>
+<%- unless missing.empty? then %>
   <h2>Missing Gem Documentation</h2>
 
   <p>You are missing documentation for some of your installed gems.

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

@@ -1,16 +1,14 @@
-<%- unless klass.extends.empty? %>
+<%- unless klass.extends.empty? then %>
 <div id="extends-section" class="nav-section">
   <h3>Extended With Modules</h3>
 
   <ul class="link-list">
   <%- klass.extends.each do |ext| %>
-    <li>
-    <%- unless String === ext.module %>
-      <a class="extend" href="<%= klass.aref_to ext.module.path %>"><%= ext.module.full_name %></a>
-    <%- else %>
-      <span class="extend"><%= ext.name %></span>
-    <%- end %>
-    </li>
+  <%- unless String === ext.module then %>
+    <li><a class="extend" href="<%= klass.aref_to ext.module.path %>"><%= ext.module.full_name %></a></li>
+  <%- else %>
+    <li><span class="extend"><%= ext.name %></span></li>
+  <%- end %>
   <%- end %>
   </ul>
 </div>

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

@@ -1,16 +1,14 @@
-<%- unless klass.includes.empty? %>
+<%- unless klass.includes.empty? then %>
 <div id="includes-section" class="nav-section">
   <h3>Included Modules</h3>
 
   <ul class="link-list">
   <%- klass.includes.each do |inc| %>
-    <li>
-    <%- unless String === inc.module %>
-      <a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a>
-    <%- else %>
-      <span class="include"><%= inc.name %></span>
-    <%- end %>
-    </li>
+  <%- unless String === inc.module then %>
+    <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a></li>
+  <%- else %>
+    <li><span class="include"><%= inc.name %></span></li>
+  <%- end %>
   <%- end %>
   </ul>
 </div>

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

@@ -5,7 +5,7 @@
   <%- installed.each do |name, href, exists, type, _| %>
     <%- next if type == :extra %>
     <li class="folder">
-    <%- if exists %>
+    <%- if exists then %>
       <a href="<%= href %>"><%= h name %></a>
     <%- else %>
       <%= h name %>

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

@@ -2,7 +2,7 @@
 <%- if defined?(current) %>
   <%- dir = current.full_name[%r{\A[^/]+(?=/)}] || current.page_name %>
 <%- end %>
-<%- unless simple_files.empty? %>
+<%- unless simple_files.empty? then %>
 <div id="fileindex-section" class="nav-section">
   <h3>Pages</h3>
 

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

@@ -1,4 +1,4 @@
-<%- unless klass.sections.length == 1 %>
+<%- unless klass.sections.length == 1 then %>
 <div id="sections-section" class="nav-section">
   <h3>Sections</h3>
 

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

@@ -1,11 +1,11 @@
-<%- comment = if current.respond_to? :comment_location
+<%- comment = if current.respond_to? :comment_location then
                current.comment_location
              else
                current.comment
              end
    table = current.parse(comment).table_of_contents.dup
 
-   if table.length > 1 %>
+   if table.length > 1 then %>
 <div class="nav-section">
   <h3>Table of Contents</h3>
 
@@ -17,18 +17,18 @@
       <%- level = table.first&.level %>
       <%- while table.first && table.first.level >= level %>
         <%- heading = table.shift %>
-        <li>
         <%- if table.first.nil? || table.first.level <= heading.level %>
-          <% display_link.call heading %>
+          <li><% display_link.call heading %></li>
         <%- else %>
+          <li>
             <details open>
               <summary><%- display_link.call heading %></summary>
               <ul class="link-list" role="directory">
                 <% list_siblings.call %>
               </ul>
             </details>
+          </li>
         <%- end %>
-        </li>
       <%- end %>
     <%- end %>