rdoc 3.2 → 3.3

data/History.txt

@@ -1,3 +1,30 @@
+=== 3.3 / ??
+
+* Minor enhancements
+  * The coverage report can now report undocumented method parameters
+    including methods defined in C.
+
+    <kbd>rdoc -C</kbd> gives a standard report, <kbd>rdoc -C1</kbd> includes
+    method parameters.  Method parameters are considered documented if they're
+    marked-up with <tt>+</tt>, <tt><code></tt> or <code><tt></code>.
+  * The C parser now uses <tt>*args</tt> instead of <tt>...</tt> if no
+    <tt>call-seq</tt> was provided to give names to the arguments.
+* Bug fixes
+  * The C parser now records the file location of aliases, attributes,
+    constants and methods allowing -C to work on C files.
+  * Darkfish now handles dots in call-seq allowing <tt>ary.insert(index,
+    obj...)</tt> to display correctly.  Patch #6 by KUBO Takehiro.
+  * Improved processing of meta-programmed methods when followed by unparseable
+    syntax.  RubyForge patch #28653 by Aidan Cully.
+  * rdoc now touches the flag file when it create the output directory.
+    Prevents the "isn't an RDoc directory" error if rdoc crashes.
+  * RDoc now properly converts to the expected output encoding.  RubyForge bug
+    #28791 by Dzmitry Prakapenka.
+  * Restored parsing of block comments.  RubyForge bug #28668 by Stefano Crocco.
+  * Metaprogrammed methods defined with blocks no longer confuse the ruby
+    parser.  RubyForge bug #28370 by Erik Hollensbe.
+  * ri no longer displays all methods in the inheritance chain.
+
 === 3.2 / 2010-12-29
 
 * Minor enhancements
@@ -28,7 +55,7 @@ otherwise noted.
     RubyForge Bug #26290 by Sylvain Joyeux.
   * Coverage report no longer crashes for constant aliases.  Pull Request #1
     by Andy Lindeman.
-  * RDoc no longer looses ghost methods when followed by certain tokens.
+  * RDoc no longer loses ghost methods when followed by certain tokens.
     RubyForge bug #27793 by Aaron Patterson.
   * RDoc no longer crashes in ri if HOME is not set.  Ruby Bug #4202 by
     Shyouhei Urabe.

data/Manifest.txt

@@ -79,6 +79,7 @@ lib/rdoc/markup/to_html.rb
 lib/rdoc/markup/to_html_crossref.rb
 lib/rdoc/markup/to_rdoc.rb
 lib/rdoc/markup/to_test.rb
+lib/rdoc/markup/to_tt_only.rb
 lib/rdoc/markup/verbatim.rb
 lib/rdoc/meta_method.rb
 lib/rdoc/method_attr.rb
@@ -139,6 +140,7 @@ test/test_rdoc_markup_to_bs.rb
 test/test_rdoc_markup_to_html.rb
 test/test_rdoc_markup_to_html_crossref.rb
 test/test_rdoc_markup_to_rdoc.rb
+test/test_rdoc_markup_to_tt_only.rb
 test/test_rdoc_method_attr.rb
 test/test_rdoc_normal_class.rb
 test/test_rdoc_normal_module.rb
@@ -153,6 +155,7 @@ test/test_rdoc_ri_driver.rb
 test/test_rdoc_ri_paths.rb
 test/test_rdoc_ri_store.rb
 test/test_rdoc_ruby_lex.rb
+test/test_rdoc_single_class.rb
 test/test_rdoc_stats.rb
 test/test_rdoc_task.rb
 test/test_rdoc_text.rb

data/lib/rdoc.rb

@@ -95,7 +95,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '3.2'
+  VERSION = '3.3'
 
   ##
   # Method visibilities

data/lib/rdoc/anon_class.rb

@@ -4,6 +4,8 @@ require 'rdoc/class_module'
 # An anonymous class like:
 #
 #   c = Class.new do end
+#
+# AnonClass is currently not used.
 
 class RDoc::AnonClass < RDoc::ClassModule
 end

data/lib/rdoc/any_method.rb

@@ -140,12 +140,41 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   end
 
   ##
-  # Pretty parameter list for this method
+  # A list of this method's method and yield parameters.  +call-seq+ params
+  # are preferred over parsed method and block params.
+
+  def param_list
+    if @call_seq then
+      params = @call_seq.split("\n").last
+      params = params.sub(/.*?\((.*)\)/, '\1')
+      params = params.sub(/(\{|do)\s*\|([^|]*)\|.*/, ',\2')
+    elsif @params then
+      params = @params.sub(/\((.*)\)/, '\1')
+
+      params << ",#{@block_params}" if @block_params
+    elsif @block_params then
+      params = @block_params
+    else
+      return []
+    end
+
+    params.gsub(/\s+/, '').split ','
+  end
+
+  ##
+  # Pretty parameter list for this method.  If the method's parameters were
+  # given by +call-seq+ it is preferred over the parsed values.
 
   def param_seq
-    params = @params.gsub(/\s*\#.*/, '')
-    params = params.tr("\n", " ").squeeze(" ")
-    params = "(#{params})" unless params[0] == ?(
+    if @call_seq then
+      params = @call_seq.split("\n").last
+      params = params.sub(/[^( ]+/, '')
+      params = params.sub(/(\|[^|]+\|)\s*\.\.\.\s*(end|\})/, '\1 \2')
+    else
+      params = @params.gsub(/\s*\#.*/, '')
+      params = params.tr("\n", " ").squeeze(" ")
+      params = "(#{params})" unless params[0] == ?(
+    end
 
     if @block_params then
       # If this method has explicit block parameters, remove any explicit

data/lib/rdoc/code_object.rb

@@ -115,6 +115,12 @@ class RDoc::CodeObject
                  if comment and not comment.empty? then
                    normalize_comment comment
                  else
+                   # TODO is this sufficient?
+                   # HACK correct fix is to have #initialize create @comment
+                   #      with the correct encoding
+                   if Object.const_defined? :Encoding and @comment.empty? then
+                     @comment.force_encoding comment.encoding
+                   end
                    @comment
                  end
                end

data/lib/rdoc/context.rb

@@ -188,7 +188,6 @@ class RDoc::Context < RDoc::CodeObject
     @in_files = []
 
     @name    ||= "unknown"
-    @comment ||= ""
     @parent  = nil
     @visibility = :public
 

data/lib/rdoc/encoding.rb

@@ -78,4 +78,3 @@ module RDoc::Encoding
 
 end
 
-

data/lib/rdoc/generator/markup.rb

@@ -1,7 +1,11 @@
+# This file is loaded by generators.  It allows RDoc's CodeObject tree to
+# avoid loading generator code to increase startup time (for ri).
+
 require 'rdoc/text'
 require 'rdoc/code_objects'
 require 'rdoc/generator'
 require 'rdoc/markup/to_html_crossref'
+require 'rdoc/ruby_token'
 
 ##
 # Handle common RDoc::Markup tasks for various CodeObjects

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

@@ -228,7 +228,7 @@
         <% if method.call_seq %>
         <% method.call_seq.strip.split("\n").each_with_index do |call_seq, i| %>
         <div class="method-heading">
-          <span class="method-callseq"><%= call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w.+\./m, '') %></span>
+          <span class="method-callseq"><%= call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w+\./m, '') %></span>
           <% if i == 0 %>
           <span class="method-click-advice">click to toggle source</span>
           <% end %>

data/lib/rdoc/markup.rb

@@ -537,8 +537,8 @@ class RDoc::Markup
   # structure (paragraphs, lists, and so on).  Invoke an event handler as we
   # identify significant chunks.
 
-  def initialize
-    @attribute_manager = RDoc::Markup::AttributeManager.new
+  def initialize attribute_manager = nil
+    @attribute_manager = attribute_manager || RDoc::Markup::AttributeManager.new
     @output = nil
   end
 

data/lib/rdoc/markup/attribute_manager.rb

@@ -74,7 +74,6 @@ class RDoc::Markup::AttributeManager
     add_html "code", :TT
   end
 
-
   ##
   # Return an attribute object with the given turn_on and turn_off bits set
 

data/lib/rdoc/markup/to_tt_only.rb

@@ -0,0 +1,114 @@
+require 'rdoc/markup/formatter'
+require 'rdoc/markup/inline'
+
+##
+# Extracts sections of text enclosed in plus, tt or code.  Used to discover
+# undocumented parameters.
+
+class RDoc::Markup::ToTtOnly < RDoc::Markup::Formatter
+
+  ##
+  # Stack of list types
+
+  attr_reader :list_type
+
+  ##
+  # Output accumulator
+
+  attr_reader :res
+
+  ##
+  # Creates a new tt-only formatter.
+
+  def initialize
+    super
+
+    add_tag :TT, nil, nil
+  end
+
+  ##
+  # Pops the list type for +list+ from #list_type
+
+  def accept_list_end list
+    @list_type.pop
+  end
+
+  ##
+  # Pushes the list type for +list+ onto #list_type
+
+  def accept_list_start list
+    @list_type << list.type
+  end
+
+  ##
+  # Prepares the visitor for consuming +list_item+
+
+  def accept_list_item_start list_item
+    case @list_type.last
+    when :NOTE, :LABEL then
+      tt_sections(list_item.label)
+    end
+  end
+
+  ##
+  # Adds +paragraph+ to the output
+
+  def accept_paragraph paragraph
+    tt_sections(paragraph.text)
+  end
+
+  ##
+  # Does nothing to +markup_item+ because it doesn't have any user-built
+  # content
+
+  def do_nothing markup_item
+  end
+
+  alias accept_blank_line    do_nothing # :nodoc:
+  alias accept_heading       do_nothing # :nodoc:
+  alias accept_list_item_end do_nothing # :nodoc:
+  alias accept_raw           do_nothing # :nodoc:
+  alias accept_rule          do_nothing # :nodoc:
+  alias accept_verbatim      do_nothing # :nodoc:
+
+  ##
+  # Extracts tt sections from +text+
+
+  def tt_sections text
+    flow = @am.flow text.dup
+
+    flow.each do |item|
+      case item
+      when String then
+        @res << item if in_tt?
+      when RDoc::Markup::AttrChanger then
+        off_tags res, item
+        on_tags res, item
+      when RDoc::Markup::Special then
+        @res << convert_special(item) if in_tt? # TODO can this happen?
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+
+    res
+  end
+
+  ##
+  # Returns an Array of items that were wrapped in plus, tt or code.
+
+  def end_accepting
+    @res.compact
+  end
+
+  ##
+  # Prepares the visitor for gathering tt sections
+
+  def start_accepting
+    @res = []
+
+    @list_type = []
+  end
+
+end
+

data/lib/rdoc/normal_class.rb

@@ -12,6 +12,13 @@ class RDoc::NormalClass < RDoc::ClassModule
     superclass ? super + [superclass] : super
   end
 
+  ##
+  # The definition of this class, <tt>class MyClassName</tt>
+
+  def definition
+    "class #{full_name}"
+  end
+
   def inspect # :nodoc:
     superclass = @superclass ? " < #{@superclass}" : nil
     "<%s:0x%x class %s%s includes: %p attributes: %p methods: %p aliases: %p>" % [

data/lib/rdoc/normal_module.rb

@@ -12,6 +12,13 @@ class RDoc::NormalModule < RDoc::ClassModule
     ]
   end
 
+  ##
+  # The definition of this module, <tt>module MyModuleName</tt>
+
+  def definition
+    "module #{full_name}"
+  end
+
   ##
   # This is a module, returns true
 

data/lib/rdoc/options.rb

@@ -455,9 +455,11 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--[no-]coverage-report", "--[no-]dcov", "-C",
+      opt.on("--[no-]coverage-report=[LEVEL]", "--[no-]dcov", "-C", Integer,
              "Prints a report on undocumented items.",
              "Does not generate files.") do |value|
+        value = 0 if value.nil? # Integer converts -C to nil
+
         @coverage_report = value
         @force_update = true if value
       end

data/lib/rdoc/parser/c.rb

@@ -156,6 +156,7 @@ class RDoc::Parser::C < RDoc::Parser
       comment = strip_stars comment
       al.comment = comment
 
+      al.record_location @top_level
       class_obj.add_alias al
       @stats.add_alias al
     end
@@ -618,6 +619,7 @@ class RDoc::Parser::C < RDoc::Parser
 
     attr = RDoc::Attr.new '', name, rw, comment
 
+    attr.record_location @top_level
     class_obj.add_attribute attr
     @stats.add_attribute attr
   end
@@ -732,6 +734,7 @@ class RDoc::Parser::C < RDoc::Parser
       con = RDoc::Constant.new const_name, definition, comment
     end
 
+    con.record_location @top_level
     @stats.add_constant con
     class_obj.add_constant con
   end
@@ -776,11 +779,12 @@ class RDoc::Parser::C < RDoc::Parser
       p_count = Integer(param_count) rescue -1
 
       if p_count < 0 then
-        meth_obj.params = "(...)"
+        meth_obj.params = "(*args)"
       elsif p_count == 0
         meth_obj.params = "()"
       else
-        meth_obj.params = "(" + (1..p_count).map{|i| "p#{i}"}.join(", ") + ")"
+        params = (1..p_count).map { |i| "p#{i}" }.join(', ')
+        meth_obj.params = "(#{params})"
       end
 
       if source_file then
@@ -797,6 +801,7 @@ class RDoc::Parser::C < RDoc::Parser
 
       if find_body(class_name, meth_body, meth_obj, body) and
          meth_obj.document_self then
+        meth_obj.record_location @top_level
         class_obj.add_method meth_obj
         @stats.add_method meth_obj
         meth_obj.visibility = :private if 'private_method' == type

data/lib/rdoc/parser/ruby.rb

@@ -658,7 +658,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
     unless TkASSIGN === eq_tk then
       unget_tk eq_tk
-      return
+      return false
     end
 
     nest = 0
@@ -669,7 +669,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     if TkGT === tk then
       unget_tk tk
       unget_tk eq_tk
-      return
+      return false
     end
 
     rhs_name = ''
@@ -725,6 +725,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
     @stats.add_constant con
     container.add_constant con if con.document_self
+    true
   end
 
   ##
@@ -764,7 +765,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       meth.comment = comment
 
       @stats.add_method meth
-    elsif comment.sub!(/# +:?(attr(_reader|_writer|_accessor)?:) *(\S*).*?\n/i, '') then
+    elsif comment.sub!(/# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i, '') then
       rw = case $1
            when 'attr_reader' then 'R'
            when 'attr_writer' then 'W'
@@ -933,6 +934,10 @@ class RDoc::Parser::Ruby < RDoc::Parser
           break unless last_tk and TkCOMMA === last_tk
         when TkSPACE then
           # expression continues
+        when TkDO then
+          unget_tk tk
+          parse_statements container, single, meth
+          break
         else
           last_tk = tk
         end
@@ -1223,6 +1228,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
     while tk = get_tk do
       keep_comment = false
+      try_parse_comment = false
 
       non_comment_seen = true unless TkCOMMENT === tk
 
@@ -1287,7 +1293,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
       when TkCONSTANT then
         if container.document_self then
-          parse_constant container, tk, comment
+          if not parse_constant container, tk, comment then
+            try_parse_comment = true
+          end
         end
 
       when TkALIAS then
@@ -1365,10 +1373,14 @@ class RDoc::Parser::Ruby < RDoc::Parser
           return
         end
       else
+        try_parse_comment = nest == 1
+      end
+
+      if try_parse_comment then
         non_comment_seen = parse_comment container, tk, comment unless
           comment.empty?
 
-        comment = ''
+        keep_comment = false
       end
 
       comment = '' unless keep_comment