rdoc 6.7.0 → 6.12.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/{any_method.rb → code_object/any_method.rb}

@@ -198,7 +198,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @full_name     = array[2]
     @singleton     = array[3]
     @visibility    = array[4]
-    @comment       = array[5]
+    @comment       = RDoc::Comment.from_document array[5]
     @call_seq      = array[6]
     @block_params  = array[7]
     #                      8 handled below
@@ -210,8 +210,8 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @section_title = array[14]
     @is_alias_for  = array[15]
 
-    array[8].each do |new_name, comment|
-      add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
+    array[8].each do |new_name, document|
+      add_alias RDoc::Alias.new(nil, @name, new_name, RDoc::Comment.from_document(document), @singleton)
     end
 
     @parent_name ||= if @full_name =~ /#/ then

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

@@ -136,7 +136,7 @@ class RDoc::Attr < RDoc::MethodAttr
     @full_name     = array[2]
     @rw            = array[3]
     @visibility    = array[4]
-    @comment       = array[5]
+    @comment       = RDoc::Comment.from_document array[5]
     @singleton     = array[6] || false # MARSHAL_VERSION == 0
     #                      7 handled below
     @parent_name   = array[8]

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
@@ -358,12 +359,14 @@ class RDoc::ClassModule < RDoc::Context
     @name       = array[1]
     @full_name  = array[2]
     @superclass = array[3]
-    @comment    = array[4]
+    document    = array[4]
 
-    @comment_location = if RDoc::Markup::Document === @comment.parts.first then
-                          @comment
+    @comment    = RDoc::Comment.from_document document
+
+    @comment_location = if RDoc::Markup::Document === document.parts.first then
+                          document
                         else
-                          RDoc::Markup::Document.new @comment
+                          RDoc::Markup::Document.new document
                         end
 
     array[5].each do |name, rw, visibility, singleton, file|
@@ -377,18 +380,18 @@ class RDoc::ClassModule < RDoc::Context
       attr.record_location RDoc::TopLevel.new file
     end
 
-    array[6].each do |constant, comment, file|
+    array[6].each do |constant, document, file|
       case constant
       when RDoc::Constant then
         add_constant constant
       else
-        constant = add_constant RDoc::Constant.new(constant, nil, comment)
+        constant = add_constant RDoc::Constant.new(constant, nil, RDoc::Comment.from_document(document))
         constant.record_location RDoc::TopLevel.new file
       end
     end
 
-    array[7].each do |name, comment, file|
-      incl = add_include RDoc::Include.new(name, comment)
+    array[7].each do |name, document, file|
+      incl = add_include RDoc::Include.new(name, RDoc::Comment.from_document(document))
       incl.record_location RDoc::TopLevel.new file
     end
 
@@ -405,8 +408,8 @@ class RDoc::ClassModule < RDoc::Context
       end
     end
 
-    array[9].each do |name, comment, file|
-      ext = add_extend RDoc::Extend.new(name, comment)
+    array[9].each do |name, document, file|
+      ext = add_extend RDoc::Extend.new(name, RDoc::Comment.from_document(document))
       ext.record_location RDoc::TopLevel.new file
     end if array[9] # Support Marshal version 1
 
@@ -443,7 +446,8 @@ class RDoc::ClassModule < RDoc::Context
 
       document = document.merge other_document
 
-      @comment = @comment_location = document
+      @comment = RDoc::Comment.from_document(document)
+      @comment_location = document
     end
 
     cm = class_module
@@ -704,10 +708,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 +829,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/{constant.rb → code_object/constant.rb}

@@ -133,7 +133,7 @@ class RDoc::Constant < RDoc::CodeObject
   # * #parent_name
 
   def marshal_load array
-    initialize array[1], nil, array[5]
+    initialize array[1], nil, RDoc::Comment.from_document(array[5])
 
     @full_name     = array[2]
     @visibility    = array[3] || :public

data/lib/rdoc/{context → code_object/context}/section.rb

@@ -61,19 +61,10 @@ class RDoc::Context::Section
   # Adds +comment+ to this section
 
   def add_comment comment
-    comment = extract_comment comment
-
-    return if comment.empty?
-
-    case comment
-    when RDoc::Comment then
-      @comments << comment
-    when RDoc::Markup::Document then
-      @comments.concat comment.parts
-    when Array then
-      @comments.concat comment
-    else
-      raise TypeError, "unknown comment type: #{comment.inspect}"
+    comments = Array(comment)
+    comments.each do |c|
+      extracted_comment = extract_comment(c)
+      @comments << extracted_comment unless extracted_comment.empty?
     end
   end
 
@@ -97,10 +88,6 @@ class RDoc::Context::Section
 
   def extract_comment comment
     case comment
-    when Array then
-      comment.map do |c|
-        extract_comment c
-      end
     when nil
       RDoc::Comment.new ''
     when RDoc::Comment then
@@ -115,8 +102,6 @@ class RDoc::Context::Section
                        end
       end
 
-      comment
-    when RDoc::Markup::Document then
       comment
     else
       raise TypeError, "unknown comment #{comment.inspect}"
@@ -135,20 +120,7 @@ class RDoc::Context::Section
   # The files comments in this section come from
 
   def in_files
-    return [] if @comments.empty?
-
-    case @comments
-    when Array then
-      @comments.map do |comment|
-        comment.file
-      end
-    when RDoc::Markup::Document then
-      @comment.parts.map do |document|
-        document.file
-      end
-    else
-      raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
-    end
+    @comments.map(&:file)
   end
 
   ##
@@ -170,7 +142,7 @@ class RDoc::Context::Section
     @parent  = nil
 
     @title    = array[1]
-    @comments = array[2]
+    @comments = array[2].parts.map { |doc| RDoc::Comment.from_document(doc) }
   end
 
   ##
@@ -178,26 +150,7 @@ class RDoc::Context::Section
   # multiple RDoc::Markup::Documents with their file set.
 
   def parse
-    case @comments
-    when String then
-      super
-    when Array then
-      docs = @comments.map do |comment, location|
-        doc = super comment
-        doc.file = location if location
-        doc
-      end
-
-      RDoc::Markup::Document.new(*docs)
-    when RDoc::Comment then
-      doc = super @comments.text, comments.format
-      doc.file = @comments.location
-      doc
-    when RDoc::Markup::Document then
-      return @comments
-    else
-      raise ArgumentError, "unknown comment class #{comments.class}"
-    end
+    RDoc::Markup::Document.new(*@comments.map(&:parse))
   end
 
   ##
@@ -213,20 +166,9 @@ class RDoc::Context::Section
   # Removes a comment from this section if it is from the same file as
   # +comment+
 
-  def remove_comment comment
-    return if @comments.empty?
-
-    case @comments
-    when Array then
-      @comments.delete_if do |my_comment|
-        my_comment.file == comment.file
-      end
-    when RDoc::Markup::Document then
-      @comments.parts.delete_if do |document|
-        document.file == comment.file.name
-      end
-    else
-      raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
+  def remove_comment target_comment
+    @comments.delete_if do |stored_comment|
+      stored_comment.file == target_comment.file
     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
 
@@ -214,7 +214,7 @@ class RDoc::TopLevel < RDoc::Context
     initialize array[1]
 
     @parser  = array[2]
-    @comment = array[3]
+    @comment = RDoc::Comment.from_document array[3]
 
     @file_stat          = nil
   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
@@ -135,7 +141,6 @@ class RDoc::CodeObject
   def comment=(comment)
     @comment = case comment
                when NilClass               then ''
-               when RDoc::Markup::Document then comment
                when RDoc::Comment          then comment.normalize
                else
                  if comment and not comment.empty? then

data/lib/rdoc/comment.rb

@@ -126,7 +126,7 @@ class RDoc::Comment
   # A comment is empty if its text String is empty.
 
   def empty?
-    @text.empty?
+    @text.empty? && (@document.nil? || @document.empty?)
   end
 
   ##
@@ -226,4 +226,14 @@ class RDoc::Comment
     @format == 'tomdoc'
   end
 
+  ##
+  # Create a new parsed comment from a document
+
+  def self.from_document(document) # :nodoc:
+    comment = RDoc::Comment.new('')
+    comment.document = document
+    comment.location = RDoc::TopLevel.new(document.file) if document.file
+    comment
+  end
+
 end

data/lib/rdoc/generator/darkfish.rb

@@ -316,11 +316,14 @@ class RDoc::Generator::Darkfish
     asset_rel_prefix = rel_prefix + @asset_rel_path
 
     @title = @options.title
+    @main_page = @files.find { |f| f.full_name == @options.main_page }
 
     render_template template_file, out_file do |io|
       here = binding
       # suppress 1.9.3 warning
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      # some partials rely on the presence of current variable to render
+      here.local_variable_set(:current, @main_page) if @main_page
       here
     end
   rescue => e
@@ -677,7 +680,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 +689,6 @@ class RDoc::Generator::Darkfish
 #{head_file.read}
 
 #{body}
-
-#{footer_file.read}
     TEMPLATE
   end
 
@@ -783,4 +783,42 @@ class RDoc::Generator::Darkfish
     template
   end
 
+  # Returns an excerpt of the comment for usage in meta description tags
+  def excerpt(comment)
+    text = case comment
+    when RDoc::Comment
+      comment.text
+    else
+      comment
+    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 %>