rdoc 6.7.0 → 6.11.0

data/TODO.rdoc

@@ -1,9 +1,10 @@
+= TODO
 This file contains some things that might happen in RDoc, or might not.
 Forward Looking Statements applies.
 
-=== RDoc::VERSION.succ
+== RDoc::VERSION.succ
 
-Blockers:
+=== Blockers:
 
 * Update LICENSE to match ruby's switch
 * The alias keyword should not be bidirectional
@@ -13,7 +14,7 @@ Blockers:
 * Fix consumption of , after link like: RDoc[rdoc-ref:RDoc], <- comma here
 * Remove support for links like Matrix[*rows]
 
-Nice to have:
+=== Nice to have:
 
 * Parse only changed files (like in ruby)
 * Page of Glory (or Shame) in HTML output showing documentation coverage
@@ -26,9 +27,9 @@ Nice to have:
 * Global variable support
 * Provide the code_object to directive handlers
 
-=== More Future
+== More Future
 
-API changes to RDoc
+=== API changes to RDoc
 
 * RDoc::TopLevel#add_method should automatically create the appropriate method
   class rather than requiring one be passed in.
@@ -36,7 +37,7 @@ API changes to RDoc
 * Add versions to RDoc::Markup syntax tree marshal format
 * Comments can no longer be Strings
 
-=== Crazy Ideas
+== Crazy Ideas
 
 * Auto-normalize heading levels to look OK.  It's weird to see an <h1> in
   the middle of a method section.
@@ -46,7 +47,7 @@ API changes to RDoc
   * Rename Context to Container
   * Rename NormalClass to Class
 
-=== Accessibility
+== Accessibility
 
 Page title in right hand side
 

data/lib/rdoc/{alias.rb → code_object/alias.rb}

@@ -70,7 +70,7 @@ class RDoc::Alias < RDoc::CodeObject
   # HTML id-friendly version of +#new_name+.
 
   def html_name
-    CGI.escape(@new_name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
+    CGI.escape(@new_name.gsub('-', '-2D')).gsub('%', '-').sub(/^-/, '')
   end
 
   def inspect # :nodoc:

data/lib/rdoc/{class_module.rb → code_object/class_module.rb}

@@ -223,6 +223,7 @@ class RDoc::ClassModule < RDoc::Context
   def complete min_visibility
     update_aliases
     remove_nodoc_children
+    embed_mixins
     update_includes
     remove_invisible min_visibility
   end
@@ -704,10 +705,37 @@ class RDoc::ClassModule < RDoc::Context
 
   ##
   # Set the superclass of this class to +superclass+
+  #
+  # where +superclass+ is one of:
+  #
+  # - +nil+
+  # - a String containing the full name of the superclass
+  # - the RDoc::ClassModule representing the superclass
 
   def superclass=(superclass)
     raise NoMethodError, "#{full_name} is a module" if module?
-    @superclass = superclass
+    case superclass
+    when RDoc::ClassModule
+      @superclass = superclass.full_name
+    when nil, String
+      @superclass = superclass
+    else
+      raise TypeError, "superclass must be a String or RDoc::ClassModule, not #{superclass.class}"
+    end
+  end
+
+  ##
+  # Get all super classes of this class in an array. The last element might be
+  # a string if the name is unknown.
+
+  def super_classes
+    result = []
+    parent = self
+    while parent = parent.superclass
+      result << parent
+      return result if parent.is_a?(String)
+    end
+    result
   end
 
   def to_s # :nodoc:
@@ -798,4 +826,43 @@ class RDoc::ClassModule < RDoc::Context
     extends.uniq!
   end
 
+  def embed_mixins
+    return unless options.embed_mixins
+
+    includes.each do |include|
+      next if String === include.module
+      include.module.method_list.each do |code_object|
+        add_method(prepare_to_embed(code_object))
+      end
+      include.module.constants.each do |code_object|
+        add_constant(prepare_to_embed(code_object))
+      end
+      include.module.attributes.each do |code_object|
+        add_attribute(prepare_to_embed(code_object))
+      end
+    end
+
+    extends.each do |ext|
+      next if String === ext.module
+      ext.module.method_list.each do |code_object|
+        add_method(prepare_to_embed(code_object, true))
+      end
+      ext.module.attributes.each do |code_object|
+        add_attribute(prepare_to_embed(code_object, true))
+      end
+    end
+  end
+
+  private
+
+  def prepare_to_embed(code_object, singleton=false)
+    code_object = code_object.dup
+    code_object.mixin_from = code_object.parent
+    code_object.singleton = true if singleton
+    set_current_section(code_object.section.title, code_object.section.comment)
+    # add_method and add_attribute will reassign self's visibility back to the method/attribute
+    # so we need to sync self's visibility with the object's to properly retain that information
+    self.visibility = code_object.visibility
+    code_object
+  end
 end

data/lib/rdoc/{method_attr.rb → code_object/method_attr.rb}

@@ -114,8 +114,8 @@ class RDoc::MethodAttr < RDoc::CodeObject
     return unless other.respond_to?(:singleton) &&
                   other.respond_to?(:name)
 
-    [     @singleton ? 0 : 1,       name] <=>
-    [other.singleton ? 0 : 1, other.name]
+    [@singleton      ? 0 : 1, name_ord_range,       name] <=>
+    [other.singleton ? 0 : 1, other.name_ord_range, other.name]
   end
 
   def == other # :nodoc:
@@ -268,8 +268,8 @@ class RDoc::MethodAttr < RDoc::CodeObject
       when 'const_get' then 'const'
       when 'new' then
         $1.split('::').last.  # ClassName => class_name
-          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+          gsub(/([a-z\d])([A-Z])/, '\1_\2').
           downcase
       else
         $2
@@ -291,7 +291,7 @@ class RDoc::MethodAttr < RDoc::CodeObject
   def html_name
     require 'cgi/util'
 
-    CGI.escape(@name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
+    CGI.escape(@name.gsub('-', '-2D')).gsub('%', '-').sub(/^-/, '')
   end
 
   ##
@@ -415,4 +415,16 @@ class RDoc::MethodAttr < RDoc::CodeObject
     end
   end
 
+  def name_ord_range # :nodoc:
+    case name.ord
+    when 0..64 # anything below "A"
+      1
+    when 91..96 # the symbols between "Z" and "a"
+      2
+    when 123..126 # 7-bit symbols above "z": "{", "|", "}", "~"
+      3
+    else # everythig else can be sorted as normal
+      4
+    end
+  end
 end

data/lib/rdoc/{top_level.rb → code_object/top_level.rb}

@@ -183,8 +183,8 @@ class RDoc::TopLevel < RDoc::Context
     "#<%s:0x%x %p modules: %p classes: %p>" % [
       self.class, object_id,
       base_name,
-      @modules.map { |n,m| m },
-      @classes.map { |n,c| c }
+      @modules.map { |n, m| m },
+      @classes.map { |n, c| c }
     ]
   end
 
@@ -254,8 +254,8 @@ class RDoc::TopLevel < RDoc::Context
       q.text "base name: #{base_name.inspect}"
       q.breakable
 
-      items = @modules.map { |n,m| m }
-      items.concat @modules.map { |n,c| c }
+      items = @modules.map { |n, m| m }
+      items.concat @modules.map { |n, c| c }
       q.seplist items do |mod| q.pp mod end
     end
   end

data/lib/rdoc/code_object.rb

@@ -96,6 +96,11 @@ class RDoc::CodeObject
 
   attr_accessor :viewer
 
+  ##
+  # When mixed-in to a class, this points to the Context in which it was originally defined.
+
+  attr_accessor :mixin_from
+
   ##
   # Creates a new CodeObject that will document itself and its children
 
@@ -111,6 +116,7 @@ class RDoc::CodeObject
     @full_name        = nil
     @store            = nil
     @track_visibility = true
+    @mixin_from       = nil
 
     initialize_visibility
   end

data/lib/rdoc/generator/darkfish.rb

@@ -677,7 +677,6 @@ class RDoc::Generator::Darkfish
     return body if body =~ /<html/
 
     head_file = @template_dir + '_head.rhtml'
-    footer_file = @template_dir + '_footer.rhtml'
 
     <<-TEMPLATE
 <!DOCTYPE html>
@@ -687,8 +686,6 @@ class RDoc::Generator::Darkfish
 #{head_file.read}
 
 #{body}
-
-#{footer_file.read}
     TEMPLATE
   end
 
@@ -783,4 +780,49 @@ class RDoc::Generator::Darkfish
     template
   end
 
+  # Returns an excerpt of the content for usage in meta description tags
+  def excerpt(content)
+    text = case content
+    when RDoc::Comment
+      content.text
+    when RDoc::Markup::Document
+      # This case is for page files that are not markdown nor rdoc
+      # We convert them to markdown for now as it's easier to extract the text
+      formatter = RDoc::Markup::ToMarkdown.new
+      formatter.start_accepting
+      formatter.accept_document(content)
+      formatter.end_accepting
+    else
+      content
+    end
+
+    # Match from a capital letter to the first period, discarding any links, so
+    # that we don't end up matching badges in the README
+    first_paragraph_match = text.match(/[A-Z][^\.:\/]+\./)
+    return text[0...150].gsub(/\n/, " ").squeeze(" ") unless first_paragraph_match
+
+    extracted_text = first_paragraph_match[0]
+    second_paragraph = first_paragraph_match.post_match.match(/[A-Z][^\.:\/]+\./)
+    extracted_text << " " << second_paragraph[0] if second_paragraph
+
+    extracted_text[0...150].gsub(/\n/, " ").squeeze(" ")
+  end
+
+  def generate_ancestor_list(ancestors, klass)
+    return '' if ancestors.empty?
+
+    ancestor = ancestors.shift
+    content = +'<ul><li>'
+
+    if ancestor.is_a?(RDoc::NormalClass)
+      content << "<a href=\"#{klass.aref_to ancestor.path}\">#{ancestor.full_name}</a>"
+    else
+      content << ancestor.to_s
+    end
+
+    # Recursively call the method for the remaining ancestors
+    content << generate_ancestor_list(ancestors, klass)
+
+    content << '</li></ul>'
+  end
 end

data/lib/rdoc/generator/pot/message_extractor.rb

@@ -29,7 +29,7 @@ class RDoc::Generator::POT::MessageExtractor
     extract_text(klass.comment_location, klass.full_name)
 
     klass.each_section do |section, constants, attributes|
-      extract_text(section.title ,"#{klass.full_name}: section title")
+      extract_text(section.title, "#{klass.full_name}: section title")
       section.comments.each do |comment|
         extract_text(comment, "#{klass.full_name}: #{section.title}")
       end

data/lib/rdoc/generator/pot/po_entry.rb

@@ -23,7 +23,7 @@ class RDoc::Generator::POT::POEntry
   attr_reader :flags
 
   ##
-  # Creates a PO entry for +msgid+. Other valus can be specified by
+  # Creates a PO entry for +msgid+. Other values can be specified by
   # +options+.
 
   def initialize msgid, options = {}

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

@@ -1,7 +1,30 @@
 <meta charset="<%= @options.charset %>">
+<meta name="viewport" content="width=device-width, initial-scale=1" />
 
 <title><%= h @title %></title>
 
+<%- if defined?(klass) -%>
+  <meta name="keywords" content="ruby,<%= h "#{klass.type},#{klass.full_name}" %>">
+
+  <%- if klass.comment.empty? -%>
+    <meta name="description" content="Documentation for the <%= h "#{klass.full_name} #{klass.type}" %>">
+  <%- else -%>
+    <meta name="description" content="<%= h "#{klass.type} #{klass.full_name}: #{excerpt(klass.comment)}" %>">
+  <%- end -%>
+<%- elsif defined?(file) -%>
+  <meta name="keywords" content="ruby,documentation,<%= h file.page_name %>">
+  <meta name="description" content="<%= h "#{file.page_name}: #{excerpt(file.comment)}" %>">
+<%- 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 } then %>
+    <meta name="description" content="<%= h "#{@title}: #{excerpt(main_page.comment)}" %>">
+  <%- else -%>
+    <meta name="description" content="Documentation for <%= h @title %>">
+  <%- end -%>
+<%- end -%>
+
 <script type="text/javascript">
   var rdoc_rel_prefix = "<%= h asset_rel_prefix %>/";
   var index_rel_prefix = "<%= h rel_prefix %>/";

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

@@ -18,6 +18,7 @@
     solo = top.one? {|klass| klass.display?}
     traverse = proc do |klasses| -%>
   <ul class="link-list">
+      <%- klasses.uniq!(&:full_name) -%>
       <%- klasses.each do |index_klass| -%>
         <%- if children = all_classes[index_klass.full_name] -%>
   <li><details<% if solo; solo = false %> open<% end %>><summary><% link.call(index_klass) %></summary>

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

@@ -1,12 +1,21 @@
-<%- unless klass.method_list.empty? then %>
-<!-- Method Quickref -->
-<div id="method-list-section" class="nav-section">
-  <h3>Methods</h3>
+<% if (class_methods = klass.class_method_list.sort).any? %>
+  <div class="nav-section">
+    <h3>Class Methods</h3>
+    <ul class="link-list" role="directory">
+      <%- class_methods.each do |meth| -%>
+      <li <%- if meth.calls_super %>class="calls-super" <%- end %>><a href="#<%= meth.aref %>"><%= h meth.name -%></a></li>
+      <%- end -%>
+    </ul>
+  </div>
+<% end %>
 
-  <ul class="link-list" role="directory">
-    <%- klass.each_method do |meth| -%>
-    <li <%- if meth.calls_super %>class="calls-super" <%- end %>><a href="#<%= meth.aref %>"><%= meth.singleton ? '::' : '#' %><%= h meth.name -%></a>
-    <%- end -%>
-  </ul>
-</div>
-<%- end -%>
+<% if (instance_methods = klass.instance_methods.sort).any? %>
+  <div class="nav-section">
+    <h3>Instance Methods</h3>
+    <ul class="link-list" role="directory">
+      <%- instance_methods.each do |meth| -%>
+      <li <%- if meth.calls_super %>class="calls-super" <%- end %>><a href="#<%= meth.aref %>"><%= h meth.name -%></a></li>
+      <%- end -%>
+    </ul>
+  </div>
+<% end %>

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

@@ -1,11 +1,6 @@
-<%- if klass.type == 'class' then %>
+<%- if klass.type == 'class' && (ancestors = klass.super_classes).any? -%>
 <div id="parent-class-section" class="nav-section">
-  <h3>Parent</h3>
-
-  <%- if klass.superclass and not String === klass.superclass then -%>
-  <p class="link"><a href="<%= klass.aref_to klass.superclass.path %>"><%= klass.superclass.full_name %></a>
-  <%- else -%>
-  <p class="link"><%= klass.superclass %>
-  <%- end -%>
+  <h3>Ancestors</h3>
+  <%= generate_ancestor_list(ancestors, klass) %>
 </div>
 <%- end -%>

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

@@ -0,0 +1,3 @@
+<div id="navigation-toggle" role="button" tabindex="0" aria-label="Toggle sidebar" aria-expanded="true" aria-controls="navigation">
+  <span aria-hidden="true">&#9776;</span>
+</div>

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

@@ -1,23 +1,24 @@
 <body id="top" role="document" class="<%= klass.type %>">
-<nav role="navigation">
+<%= render '_sidebar_toggle.rhtml' %>
+
+<nav id="navigation" role="navigation">
   <div id="project-navigation">
     <%= render '_sidebar_navigation.rhtml' %>
     <%= render '_sidebar_search.rhtml' %>
   </div>
 
   <%= render '_sidebar_table_of_contents.rhtml' %>
+  <%= render '_sidebar_sections.rhtml' %>
+  <%= render '_sidebar_parent.rhtml' %>
+  <%= render '_sidebar_includes.rhtml' %>
+  <%= render '_sidebar_extends.rhtml' %>
+  <%= render '_sidebar_methods.rhtml' %>
 
-  <div id="class-metadata">
-    <%= render '_sidebar_sections.rhtml' %>
-    <%= render '_sidebar_parent.rhtml' %>
-    <%= render '_sidebar_includes.rhtml' %>
-    <%= render '_sidebar_extends.rhtml' %>
-    <%= render '_sidebar_methods.rhtml' %>
-  </div>
+  <%= render '_footer.rhtml' %>
 </nav>
 
 <main role="main" aria-labelledby="<%=h klass.aref %>">
-  <h1 id="<%=h klass.aref %>" class="<%= klass.type %>">
+  <h1 id="<%=h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>
 
@@ -26,7 +27,7 @@
   </section>
 
   <%- klass.each_section do |section, constants, attributes| -%>
-  <section id="<%= section.aref %>" class="documentation-section">
+  <section id="<%= section.aref %>" class="documentation-section anchor-link">
     <%- if section.title then -%>
     <header class="documentation-section-title">
       <h2>
@@ -53,7 +54,13 @@
       <%- constants.each do |const| -%>
         <dt id="<%= const.name %>"><%= const.name %>
         <%- if const.comment then -%>
-        <dd><%= const.description.strip %>
+        <dd>
+          <%- 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>
+          <%- end -%>
+          <%= const.description.strip %>
         <%- else -%>
         <dd class="missing-docs">(Not documented)
         <%- end -%>
@@ -69,13 +76,20 @@
       </header>
 
       <%- attributes.each do |attrib| -%>
-      <div id="<%= attrib.aref %>" class="method-detail">
+      <div id="<%= attrib.aref %>" class="method-detail anchor-link">
         <div class="method-heading attribute-method-heading">
-          <span class="method-name"><%= h attrib.name %></span><span
-            class="attribute-access-type">[<%= attrib.rw %>]</span>
+          <a href="#<%= attrib.aref %>" title="Link to this attribute">
+            <span class="method-name"><%= h attrib.name %></span>
+            <span class="attribute-access-type">[<%= attrib.rw %>]</span>
+          </a>
         </div>
 
         <div class="method-description">
+        <%- 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 then -%>
         <%= attrib.description.strip %>
         <%- else -%>
@@ -91,44 +105,62 @@
        next if visibilities.empty?
        visibilities.each do |visibility, methods|
          next if methods.empty? %>
-     <section id="<%= visibility %>-<%= type %>-<%= section.aref %>-method-details" class="method-section">
+     <section id="<%= visibility %>-<%= type %>-<%= section.aref %>-method-details" class="method-section anchor-link">
        <header>
          <h3><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3>
        </header>
 
     <%- methods.each do |method| -%>
-      <div id="<%= method.aref %>" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>">
+      <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) then -%>
-          <%-   call_seq.strip.split("\n").each_with_index do |call_seq, i| -%>
-          <div class="method-heading">
-            <span class="method-callseq">
-              <%= h(call_seq.strip.
-                    gsub( /^\w+\./m, '')).
-                    gsub(/(.*)[-=]&gt;/, '\1&rarr;') %>
-            </span>
-            <%- if i == 0 and method.token_stream then -%>
-            <span class="method-click-advice">click to toggle source</span>
+            <%- 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">
+                  <span class="method-callseq">
+                    <%= h(call_seq.strip.
+                        gsub( /^\w+\./m, '')).
+                        gsub(/(.*)[-=]&gt;/, '\1&rarr;') %>
+                  </span>
+                </a>
+              </div>
             <%- end -%>
-          </div>
-          <%-   end -%>
           <%- elsif method.has_call_seq? then -%>
-          <div class="method-heading">
-            <span class="method-name"><%= h method.name %></span>
-          </div>
+            <div class="method-heading">
+              <a href="#<%= method.aref %>" title="Link to this method">
+                <span class="method-name"><%= h method.name %></span>
+              </a>
+            </div>
           <%- else -%>
-          <div class="method-heading">
-            <span class="method-name"><%= h method.name %></span><span
-              class="method-args"><%= h method.param_seq %></span>
-            <%- if method.token_stream then -%>
-            <span class="method-click-advice">click to toggle source</span>
-            <%- end -%>
-          </div>
+            <div class="method-heading">
+              <a href="#<%= method.aref %>" title="Link to this method">
+                <span class="method-name"><%= h method.name %></span>
+                <span class="method-args"><%= h method.param_seq %></span>
+              </a>
+            </div>
           <%- end -%>
         </div>
 
+        <%- if method.token_stream -%>
+          <div class="method-controls">
+            <details class="method-source-toggle">
+              <summary>Source</summary>
+            </details>
+          </div>
+        <%- end -%>
+
         <%- unless method.skip_description? then -%>
         <div class="method-description">
+          <%- if method.token_stream then -%>
+          <div class="method-source-code" id="<%= method.html_name %>-source">
+            <pre><%= method.markup_code %></pre>
+          </div>
+          <%- end -%>
+          <%- 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 then -%>
           <%= method.description.strip %>
           <%- else -%>
@@ -143,12 +175,6 @@
               %>
             </div>
           <%- end -%>
-
-          <%- if method.token_stream then -%>
-          <div class="method-source-code" id="<%= method.html_name %>-source">
-            <pre><%= method.markup_code %></pre>
-          </div>
-          <%- end -%>
         </div>
         <%- end -%>