rdoc 3.8 → 3.9

data/lib/rdoc/parser.rb

@@ -106,6 +106,8 @@ class RDoc::Parser
   # Applies +directive+'s +value+ to +code_object+, if appropriate
 
   def self.process_directive code_object, directive, value
+    warn "RDoc::Parser::process_directive is deprecated and wil be removed in RDoc 4.  Use RDoc::Markup::PreProcess#handle_directive instead" if $-w
+
     case directive
     when 'nodoc' then
       code_object.document_self = nil # notify nodoc
@@ -196,6 +198,9 @@ class RDoc::Parser
     @content = content
     @options = options
     @stats = stats
+
+    @preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
+    @preprocess.options = @options
   end
 
 end

data/lib/rdoc/parser/c.rb

@@ -645,9 +645,7 @@ class RDoc::Parser::C < RDoc::Parser
       meth_obj.call_seq = $1.strip
     end
 
-    if comment.sub!(/\s*:(nodoc|doc|yields?|args?):\s*(.*)/, '') then
-      RDoc::Parser.process_directive meth_obj, $1, $2
-    end
+    look_for_directives_in meth_obj, comment
   end
 
   ##
@@ -913,12 +911,10 @@ class RDoc::Parser::C < RDoc::Parser
   #    * :title: My Awesome Project
   #    */
   #
-  # This routine modifies its parameter
-
-  def look_for_directives_in(context, comment)
-    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
+  # This method modifies the +comment+
 
-    preprocess.handle comment, context do |directive, param|
+  def look_for_directives_in context, comment
+    @preprocess.handle comment, context do |directive, param|
       case directive
       when 'main' then
         @options.main_page = param

data/lib/rdoc/parser/ruby.rb

@@ -405,17 +405,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
   #
   # This routine modifies its +comment+ parameter.
 
-  def look_for_directives_in(context, comment)
-    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
-
-    preprocess.handle comment, context do |directive, param|
+  def look_for_directives_in context, comment
+    @preprocess.handle comment, context do |directive, param|
       case directive
-      when 'enddoc' then
-        context.done_documenting = true
-        ''
-      when 'main' then
-        @options.main_page = param if @options.respond_to? :main_page
-        ''
       when 'method', 'singleton-method',
            'attr', 'attr_accessor', 'attr_reader', 'attr_writer' then
         false # handled elsewhere
@@ -423,16 +415,6 @@ class RDoc::Parser::Ruby < RDoc::Parser
         context.set_current_section param, comment
         comment.replace ''
         break
-      when 'startdoc' then
-        context.start_doc
-        context.force_documentation = true
-        ''
-      when 'stopdoc' then
-        context.stop_doc
-        ''
-      when 'title' then
-        @options.default_title = param if @options.respond_to? :default_title=
-        ''
       end
     end
 
@@ -629,6 +611,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
       cls_type = single == SINGLE ? RDoc::SingleClass : RDoc::NormalClass
       cls = declaration_context.add_class cls_type, given_name, superclass
+      cls.ignore unless container.document_children
 
       read_documentation_modifiers cls, RDoc::CLASS_MODIFIERS
       cls.record_location @top_level
@@ -679,7 +662,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
   ##
   # Parses a constant in +context+ with +comment+
 
-  def parse_constant(container, tk, comment)
+  def parse_constant container, tk, comment
     offset  = tk.seek
     line_no = tk.line_no
 
@@ -718,7 +701,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
       when TkRPAREN, TkRBRACE, TkRBRACK, TkEND then
         nest -= 1
       when TkCOMMENT then
-        if nest <= 0 && @scanner.lex_state == EXPR_END
+        if nest <= 0 &&
+           (@scanner.lex_state == EXPR_END || !@scanner.continue) then
           unget_tk tk
           break
         end
@@ -733,7 +717,6 @@ class RDoc::Parser::Ruby < RDoc::Parser
                 end
 
           container.add_module_alias mod, name, @top_level if mod
-          get_tk # TkNL
           break
         end
       when TkNL then
@@ -1327,11 +1310,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
         keep_comment = true
 
       when TkCLASS then
-        if container.document_children then
-          parse_class container, single, tk, comment
-        else
-          nest += 1
-        end
+        parse_class container, single, tk, comment
 
       when TkMODULE then
         if container.document_children then
@@ -1516,11 +1495,13 @@ class RDoc::Parser::Ruby < RDoc::Parser
   ##
   # Parses statements in the top-level +container+
 
-  def parse_top_level_statements(container)
+  def parse_top_level_statements container
     comment = collect_first_comment
-    look_for_directives_in(container, comment)
+    look_for_directives_in container, comment
+
     # HACK move if to RDoc::Context#comment=
     container.comment = comment if container.document_self unless comment.empty?
+
     parse_statements container, NORMAL, nil, comment
   end
 
@@ -1643,16 +1624,17 @@ class RDoc::Parser::Ruby < RDoc::Parser
   # Handles the directive for +context+ if the directive is listed in +allow+.
   # This method is called for directives following a definition.
 
-  def read_documentation_modifiers(context, allow)
+  def read_documentation_modifiers context, allow
     directive, value = read_directive allow
 
     return unless directive
 
-    case directive
-    when 'notnew', 'not_new', 'not-new' then
-      context.dont_rename_initialize = true
-    else
-      RDoc::Parser.process_directive context, directive, value
+    @preprocess.handle_directive '', directive, value, context do |dir, param|
+      if %w[notnew not_new not-new].include? dir then
+        context.dont_rename_initialize = true
+
+        true
+      end
     end
   end
 

data/lib/rdoc/parser/ruby_tools.rb

@@ -153,6 +153,8 @@ module RDoc::Parser::RubyTools
     @token_listeners.each do |obj|
       obj.pop_token
     end if @token_listeners
+
+    nil
   end
 
 end

data/lib/rdoc/ri/driver.rb

@@ -387,6 +387,8 @@ Options may also be set in the 'RI' environment variable.
                   klass.superclass unless klass.module?
                 end.compact.shift || 'Object'
 
+                superclass = superclass.full_name unless String === superclass
+
                 "#{name} < #{superclass}"
               end
 
@@ -451,7 +453,7 @@ Options may also be set in the 'RI' environment variable.
   # Adds a list of +methods+ to +out+ with a heading of +name+
 
   def add_method_list out, methods, name
-    return unless methods
+    return if methods.empty?
 
     out << RDoc::Markup::Heading.new(1, "#{name}:")
     out << RDoc::Markup::BlankLine.new
@@ -518,11 +520,13 @@ Options may also be set in the 'RI' environment variable.
 
     found.each do |store, klass|
       comment = klass.comment
-      class_methods    = store.class_methods[klass.full_name]
-      instance_methods = store.instance_methods[klass.full_name]
-      attributes       = store.attributes[klass.full_name]
+      # TODO the store's cache should always return an empty Array
+      class_methods    = store.class_methods[klass.full_name]    || []
+      instance_methods = store.instance_methods[klass.full_name] || []
+      attributes       = store.attributes[klass.full_name]       || []
 
-      if comment.empty? and !(instance_methods or class_methods) then
+      if comment.empty? and
+         instance_methods.empty? and class_methods.empty? then
         also_in << store
         next
       end
@@ -531,7 +535,17 @@ Options may also be set in the 'RI' environment variable.
 
       unless comment.empty? then
         out << RDoc::Markup::Rule.new(1)
-        out << comment
+
+        if comment.merged? then
+          parts = comment.parts
+          parts = parts.zip [RDoc::Markup::BlankLine.new] * parts.length
+          parts.flatten!
+          parts.pop
+
+          out.push(*parts)
+        else
+          out << comment
+        end
       end
 
       if class_methods or instance_methods or not klass.constants.empty? then
@@ -554,13 +568,12 @@ Options may also be set in the 'RI' environment variable.
         end)
 
         out << list
+        out << RDoc::Markup::BlankLine.new
       end
 
       add_method_list out, class_methods,    'Class methods'
       add_method_list out, instance_methods, 'Instance methods'
       add_method_list out, attributes,       'Attributes'
-
-      out << RDoc::Markup::BlankLine.new
     end
 
     add_also_in out, also_in
@@ -1090,11 +1103,11 @@ Options may also be set in the 'RI' environment variable.
   # NOTE: Given Foo::Bar, Bar is considered a class even though it may be a
   #       method
 
-  def parse_name(name)
+  def parse_name name
     parts = name.split(/(::|#|\.)/)
 
     if parts.length == 1 then
-      if parts.first =~ /^[a-z]/ then
+      if parts.first =~ /^[a-z]|^([%&*+\/<>^`|~-]|\+@|-@|<<|<=>?|===?|=>|=~|>>|\[\]=?|~@)$/ then
         type = '.'
         meth = parts.pop
       else

data/test/test_rdoc_code_object.rb

@@ -67,6 +67,30 @@ class TestRDocCodeObject < XrefTestCase
     assert_equal Encoding::UTF_8, @co.comment.encoding
   end
 
+  def test_display_eh_document_self
+    assert @co.display?
+
+    @co.document_self = false
+
+    refute @co.display?
+  end
+
+  def test_display_eh_ignore
+    assert @co.display?
+
+    @co.ignore
+
+    refute @co.display?
+
+    @co.stop_doc
+
+    refute @co.display?
+
+    @co.done_documenting = false
+
+    refute @co.display?
+  end
+
   def test_document_children_equals
     @co.document_children = false
     refute @co.document_children
@@ -156,6 +180,22 @@ class TestRDocCodeObject < XrefTestCase
     assert_nil @co.instance_variable_get(:@full_name)
   end
 
+  def test_ignore
+    @co.ignore
+
+    refute @co.document_self
+    refute @co.document_children
+    assert @co.ignored?
+  end
+
+  def test_ignore_eh
+    refute @co.ignored?
+
+    @co.ignore
+
+    assert @co.ignored?
+  end
+
   def test_line
     @c1_m.line = 5
 
@@ -202,10 +242,16 @@ class TestRDocCodeObject < XrefTestCase
   end
 
   def test_record_location
-    c = RDoc::CodeObject.new
-    c.record_location @xref_data
+    @co.record_location @xref_data
 
-    assert_equal 'xref_data.rb', c.file.relative_name
+    assert_equal 'xref_data.rb', @co.file.relative_name
+  end
+
+  def test_record_location_ignored
+    @co.ignore
+    @co.record_location @xref_data
+
+    refute @co.ignored?
   end
 
   def test_start_doc
@@ -218,6 +264,16 @@ class TestRDocCodeObject < XrefTestCase
     assert @co.document_children
   end
 
+  def test_start_doc_ignored
+    @co.ignore
+
+    @co.start_doc
+
+    assert @co.document_self
+    assert @co.document_children
+    refute @co.ignored?
+  end
+
   def test_stop_doc
     @co.document_self = true
     @co.document_children = true

data/test/test_rdoc_cross_reference.rb

@@ -0,0 +1,154 @@
+require 'rubygems'
+require 'minitest/autorun'
+require File.expand_path '../xref_test_case', __FILE__
+
+class TestRDocCrossReference < XrefTestCase
+
+  def setup
+    super
+
+    @xref = RDoc::CrossReference.new @c1
+  end
+
+  def assert_ref expected, name
+    assert_equal expected, @xref.resolve(name, 'fail')
+  end
+
+  def refute_ref name
+    assert_equal name, @xref.resolve(name, name)
+  end
+
+  def test_resolve_C2
+    @xref = RDoc::CrossReference.new @c2
+
+    refute_ref '#m'
+
+    assert_ref @c1__m,    'C1::m'
+    assert_ref @c2_c3,    'C2::C3'
+    assert_ref @c2_c3_m,  'C2::C3#m'
+    assert_ref @c2_c3_h1, 'C3::H1'
+    assert_ref @c4,       'C4'
+
+    assert_ref @c3_h2, 'C3::H2'
+    refute_ref 'H1'
+  end
+
+  def test_resolve_C2_C3
+    @xref = RDoc::CrossReference.new @c2_c3
+
+    assert_ref @c2_c3_m, '#m'
+
+    assert_ref @c2_c3, 'C3'
+    assert_ref @c2_c3_m, 'C3#m'
+
+    assert_ref @c2_c3_h1, 'H1'
+    assert_ref @c2_c3_h1, 'C3::H1'
+
+    assert_ref @c4, 'C4'
+
+    assert_ref @c3_h2, 'C3::H2'
+  end
+
+  def test_resolve_C3
+    @xref = RDoc::CrossReference.new @c3
+
+    assert_ref @c3, 'C3'
+
+    refute_ref '#m'
+    refute_ref 'C3#m'
+
+    assert_ref @c3_h1, 'H1'
+
+    assert_ref @c3_h1, 'C3::H1'
+    assert_ref @c3_h2, 'C3::H2'
+
+    assert_ref @c4, 'C4'
+  end
+
+  def test_resolve_C4
+    @xref = RDoc::CrossReference.new @c4
+
+    # C4 ref inside a C4 containing a C4 should resolve to the contained class
+    assert_ref @c4_c4, 'C4'
+  end
+
+  def test_resolve_C4_C4
+    @xref = RDoc::CrossReference.new @c4_c4
+
+    # A C4 reference inside a C4 class contained within a C4 class should
+    # resolve to the inner C4 class.
+    assert_ref @c4_c4, 'C4'
+  end
+
+  def test_resolve_class
+    assert_ref @c1, 'C1'
+    refute_ref 'H1'
+
+    assert_ref @c2,       'C2'
+    assert_ref @c2_c3,    'C2::C3'
+    assert_ref @c2_c3_h1, 'C2::C3::H1'
+
+    assert_ref @c3,    '::C3'
+    assert_ref @c3_h1, '::C3::H1'
+
+    assert_ref @c4_c4, 'C4::C4'
+  end
+
+  def test_resolve_file
+    assert_ref @xref_data, 'xref_data.rb'
+  end
+
+  def test_resolve_method
+    assert_ref @c1__m, 'm'
+    assert_ref @c1_m,  '#m'
+    assert_ref @c1__m, '::m'
+
+    assert_ref @c1_m,  'C1#m'
+    assert_ref @c1__m, 'C1.m'
+    assert_ref @c1__m, 'C1::m'
+
+    assert_ref @c1_m, 'C1#m'
+    assert_ref @c1_m, 'C1#m()'
+    assert_ref @c1_m, 'C1#m(*)'
+
+    assert_ref @c1__m, 'C1.m'
+    assert_ref @c1__m, 'C1.m()'
+    assert_ref @c1__m, 'C1.m(*)'
+
+    assert_ref @c1__m, 'C1::m'
+    assert_ref @c1__m, 'C1::m()'
+    assert_ref @c1__m, 'C1::m(*)'
+
+    assert_ref @c2_c3_m, 'C2::C3#m'
+
+    assert_ref @c2_c3_m, 'C2::C3.m'
+
+    # TODO stop escaping - HTML5 allows anything but space
+    assert_ref @c2_c3_h1_meh, 'C2::C3::H1#m?'
+
+    assert_ref @c2_c3_m, '::C2::C3#m'
+    assert_ref @c2_c3_m, '::C2::C3#m()'
+    assert_ref @c2_c3_m, '::C2::C3#m(*)'
+  end
+
+  def test_resolve_no_ref
+    assert_equal '', @xref.resolve('', '')
+
+    assert_equal "bogus",     @xref.resolve("bogus",     "bogus")
+    assert_equal "\\bogus",   @xref.resolve("\\bogus",   "\\bogus")
+    assert_equal "\\\\bogus", @xref.resolve("\\\\bogus", "\\\\bogus")
+
+    assert_equal "\\#n",    @xref.resolve("\\#n",    "fail")
+    assert_equal "\\#n()",  @xref.resolve("\\#n()",  "fail")
+    assert_equal "\\#n(*)", @xref.resolve("\\#n(*)", "fail")
+
+    assert_equal "C1",   @xref.resolve("\\C1",   "fail")
+    assert_equal "::C3", @xref.resolve("\\::C3", "fail")
+
+    assert_equal "succeed",      @xref.resolve("::C3::H1#n",    "succeed")
+    assert_equal "succeed",      @xref.resolve("::C3::H1#n(*)", "succeed")
+    assert_equal "\\::C3::H1#n", @xref.resolve("\\::C3::H1#n",  "fail")
+  end
+
+end
+