* lib/rdoc: Update to RDoc 3.9. Fixed `ri []`, stopdoc creating an

	  object reference, nodoc for class aliases, verbatim === lines.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32767 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

11 files changed, 763 insertions, 283 deletions

diff --git a/test/rdoc/test_rdoc_code_object.rb b/test/rdoc/test_rdoc_code_object.rb
index cdac7eeed6..89dc4b1744 100644
--- a/test/rdoc/test_rdoc_code_object.rb
+++ b/test/rdoc/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
diff --git a/test/rdoc/test_rdoc_cross_reference.rb b/test/rdoc/test_rdoc_cross_reference.rb
new file mode 100644
index 0000000000..06062ba125
--- /dev/null
+++ b/test/rdoc/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
+
diff --git a/test/rdoc/test_rdoc_generator_darkfish.rb b/test/rdoc/test_rdoc_generator_darkfish.rb
index b99803bac1..faea1ae34a 100644
--- a/test/rdoc/test_rdoc_generator_darkfish.rb
+++ b/test/rdoc/test_rdoc_generator_darkfish.rb
@@ -38,6 +38,7 @@ class TestRDocGeneratorDarkfish < MiniTest::Unit::TestCase
 
     @top_level = RDoc::TopLevel.new 'file.rb'
     @klass = @top_level.add_class RDoc::NormalClass, 'Object'
+
     @meth = RDoc::AnyMethod.new nil, 'method'
     @meth_bang = RDoc::AnyMethod.new nil, 'method!'
     @attr = RDoc::Attr.new nil, 'attr', 'RW', ''
@@ -45,6 +46,9 @@ class TestRDocGeneratorDarkfish < MiniTest::Unit::TestCase
     @klass.add_method @meth
     @klass.add_method @meth_bang
     @klass.add_attribute @attr
+
+    @ignored = @top_level.add_class RDoc::NormalClass, 'Ignored'
+    @ignored.ignore
   end
 
   def teardown
@@ -83,6 +87,8 @@ class TestRDocGeneratorDarkfish < MiniTest::Unit::TestCase
                  File.read('Object.html'))
     assert_match(/<meta content="text\/html; charset=#{encoding}"/,
                  File.read('file_rb.html'))
+
+    refute_match(/Ignored/, File.read('index.html'))
   end
 
   def test_generate_dry_run
diff --git a/test/rdoc/test_rdoc_markup_document.rb b/test/rdoc/test_rdoc_markup_document.rb
index 6b4b5892ab..9eea019ae4 100644
--- a/test/rdoc/test_rdoc_markup_document.rb
+++ b/test/rdoc/test_rdoc_markup_document.rb
@@ -124,6 +124,24 @@ class TestRDocMarkupDocument < MiniTest::Unit::TestCase
     assert_equal expected, result
   end
 
+  def test_merge_empty
+    original = @RM::Document.new
+    root = @RM::Document.new original
+
+    replace = @RM::Document.new @RM::Paragraph.new 'replace'
+    replace.file = 'file.rb'
+
+    other = @RM::Document.new replace
+
+    result = root.merge other
+
+    inner = @RM::Document.new @RM::Paragraph.new 'replace'
+    inner.file = 'file.rb'
+    expected = @RM::Document.new inner
+
+    assert_equal expected, result
+  end
+
   def test_push
     @d.push @RM::BlankLine.new, @RM::BlankLine.new
 
diff --git a/test/rdoc/test_rdoc_markup_parser.rb b/test/rdoc/test_rdoc_markup_parser.rb
index 98c16a18ef..a9d2a1b4fb 100644
--- a/test/rdoc/test_rdoc_markup_parser.rb
+++ b/test/rdoc/test_rdoc_markup_parser.rb
@@ -1366,6 +1366,44 @@ Example heading:
     assert_equal expected, @RMP.tokenize(str)
   end
 
+  def test_tokenize_verbatim_rule
+    str = <<-STR
+  Verbatim section here that is double-underlined
+  ===============================================
+    STR
+
+    expected = [
+      [:TEXT,    'Verbatim section here that is double-underlined',  2, 0],
+      [:NEWLINE, "\n",                                              49, 0],
+      [:HEADER,  47,                                                 2, 1],
+      [:NEWLINE, "\n",                                              49, 1],
+    ]
+
+    assert_equal expected, @RMP.tokenize(str)
+  end
+
+  def test_tokenize_verbatim_rule_fancy
+    str = <<-STR
+  A
+    b
+  ===============================================
+    c
+    STR
+
+    expected = [
+      [:TEXT,    'A',   2, 0],
+      [:NEWLINE, "\n",  3, 0],
+      [:TEXT,    'b',   4, 1],
+      [:NEWLINE, "\n",  5, 1],
+      [:HEADER,  47,    2, 2],
+      [:NEWLINE, "\n", 49, 2],
+      [:TEXT,    'c',   4, 3],
+      [:NEWLINE, "\n",  5, 3],
+    ]
+
+    assert_equal expected, @RMP.tokenize(str)
+  end
+
   # HACK move to Verbatim test case
   def test_verbatim_normalize
     v = @RM::Verbatim.new "foo\n", "\n", "\n", "bar\n"
diff --git a/test/rdoc/test_rdoc_markup_pre_process.rb b/test/rdoc/test_rdoc_markup_pre_process.rb
index 587a680f28..9a0a302b3e 100644
--- a/test/rdoc/test_rdoc_markup_pre_process.rb
+++ b/test/rdoc/test_rdoc_markup_pre_process.rb
@@ -5,6 +5,7 @@ require 'rubygems'
 require 'minitest/autorun'
 require 'rdoc/markup/pre_process'
 require 'rdoc/code_objects'
+require 'rdoc/options'
 
 class TestRDocMarkupPreProcess < MiniTest::Unit::TestCase
 
@@ -19,6 +20,8 @@ class TestRDocMarkupPreProcess < MiniTest::Unit::TestCase
   end
 
   def teardown
+    RDoc::Markup::PreProcess.registered.clear
+
     @tempfile.close
   end
 
@@ -73,6 +76,14 @@ contents of a string.
   end
 
   def test_handle
+    text = "# :main: M\n"
+    out = @pp.handle text
+
+    assert_same out, text
+    assert_equal "#\n", text
+  end
+
+  def test_handle_unregistered
     text = "# :x: y\n"
     out = @pp.handle text
 
@@ -80,142 +91,329 @@ contents of a string.
     assert_equal "# :x: y\n", text
   end
 
-  def test_handle_block
-    text = "# :x: y\n"
+  def test_handle_directive_blankline
+    result = @pp.handle_directive '#', 'arg', 'a, b'
+
+    assert_equal "#\n", result
+  end
+
+  def test_handle_directive_downcase
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'ARG', 'a, b', method
+
+    assert_equal 'a, b', method.params
+  end
+
+  def test_handle_directive_arg
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'arg', 'a, b', method
+
+    assert_equal 'a, b', method.params
+  end
+
+  def test_handle_directive_arg_no_context
+    result = @pp.handle_directive '', 'arg', 'a, b', nil
+
+    assert_equal "\n", result
+  end
+
+  def test_handle_directive_args
+    method = RDoc::AnyMethod.new nil, 'm'
 
-    @pp.handle text do |directive, param|
+    @pp.handle_directive '', 'args', 'a, b', method
+
+    assert_equal 'a, b', method.params
+  end
+
+  def test_handle_directive_block
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
+      ''
+    end
+
+    assert_empty result
+  end
+
+  def test_handle_directive_block_false
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       false
     end
 
-    assert_equal "# :x: y\n", text
+    assert_equal ":x: y\n", result
+  end
 
-    @pp.handle text do |directive, param|
-      ''
+  def test_handle_directive_block_nil
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
+      nil
     end
 
-    assert_equal "", text
+    assert_equal ":x: y\n", result
   end
 
-  def test_handle_category
+  def test_handle_directive_category
     context = RDoc::Context.new
     original_section = context.current_section
 
-    text = "# :category: other\n"
-
-    @pp.handle text, context
+    @pp.handle_directive '', 'category', 'other', context
 
     refute_equal original_section, context.current_section
   end
 
-  def test_handle_code_object
-    cd = RDoc::CodeObject.new
-    text = "# :x: y\n"
-    @pp.handle text, cd
+  def test_handle_directive_doc
+    code_object = RDoc::CodeObject.new
+    code_object.document_self = false
+    code_object.force_documentation = false
 
-    assert_equal "# :x: y\n", text
-    assert_equal 'y', cd.metadata['x']
+    @pp.handle_directive '', 'doc', nil, code_object
+
+    assert code_object.document_self
+    assert code_object.force_documentation
+  end
 
-    cd.metadata.clear
-    text = "# :x:\n"
-    @pp.handle text, cd
+  def test_handle_directive_doc_no_context
+    result = @pp.handle_directive '', 'doc', nil
 
-    assert_equal "# :x: \n", text
-    assert_includes cd.metadata, 'x'
+    assert_equal "\n", result
   end
 
-  def test_handle_code_object_block
-    cd = RDoc::CodeObject.new
-    text = "# :x: y\n"
-    @pp.handle text, cd do
-      false
-    end
+  def test_handle_directive_enddoc
+    code_object = RDoc::CodeObject.new
 
-    assert_equal "# :x: y\n", text
-    assert_empty cd.metadata
+    @pp.handle_directive '', 'enddoc', nil, code_object
 
-    @pp.handle text, cd do
-      nil
-    end
+    assert code_object.done_documenting
+  end
 
-    assert_equal "# :x: y\n", text
-    assert_equal 'y', cd.metadata['x']
+  def test_handle_directive_include
+    @tempfile.write 'included'
+    @tempfile.flush
 
-    cd.metadata.clear
+    result = @pp.handle_directive '', 'include', @file_name
 
-    @pp.handle text, cd do
-      ''
-    end
+    assert_equal 'included', result
+  end
+
+  def test_handle_directive_main
+    @pp.options = RDoc::Options.new
+
+    @pp.handle_directive '', 'main', 'M'
+
+    assert_equal 'M', @pp.options.main_page
+  end
+
+  def test_handle_directive_notnew
+    m = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'notnew', nil, m
+
+    assert m.dont_rename_initialize
+  end
+
+  def test_handle_directive_not_new
+    m = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'not_new', nil, m
+
+    assert m.dont_rename_initialize
+  end
+
+  def test_handle_directive_not_dash_new
+    m = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'not-new', nil, m
+
+    assert m.dont_rename_initialize
+  end
+
+  def test_handle_directive_nodoc
+    code_object = RDoc::CodeObject.new
+    code_object.document_self = true
+    code_object.document_children = true
 
-    assert_equal '', text
-    assert_empty cd.metadata
+    @pp.handle_directive '', 'nodoc', nil, code_object
+
+    refute code_object.document_self
+    assert code_object.document_children
+  end
+
+  def test_handle_directive_nodoc_all
+    code_object = RDoc::CodeObject.new
+    code_object.document_self = true
+    code_object.document_children = true
+
+    @pp.handle_directive '', 'nodoc', 'all', code_object
+
+    refute code_object.document_self
+    refute code_object.document_children
   end
 
-  def test_handle_registered
+  def test_handle_directive_nodoc_no_context
+    result = @pp.handle_directive '', 'nodoc', nil
+
+    assert_equal "\n", result
+  end
+
+  def test_handle_directive_registered
     RDoc::Markup::PreProcess.register 'x'
-    text = "# :x: y\n"
-    @pp.handle text
 
-    assert_equal '', text
+    result = @pp.handle_directive '', 'x', 'y'
 
-    text = "# :x: y\n"
+    assert_nil result
 
-    @pp.handle text do |directive, param|
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       false
     end
 
-    assert_equal "# :x: y\n", text
-
-    text = "# :x: y\n"
+    assert_equal ":x: y\n", result
 
-    @pp.handle text do |directive, param|
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       ''
     end
 
-    assert_equal "", text
+    assert_equal '', result
   end
 
-  def test_handle_registered_block
+  def test_handle_directive_registered_block
     called = nil
+
     RDoc::Markup::PreProcess.register 'x' do |directive, param|
       called = [directive, param]
       'blah'
     end
 
-    text = "# :x: y\n"
-    @pp.handle text
+    result = @pp.handle_directive '', 'x', 'y'
 
-    assert_equal 'blah', text
+    assert_equal 'blah', result
     assert_equal %w[x y], called
   end
 
-  def test_handle_registered_code_object
+  def test_handle_directive_registered_code_object
     RDoc::Markup::PreProcess.register 'x'
-    cd = RDoc::CodeObject.new
+    code_object = RDoc::CodeObject.new
 
-    text = "# :x: y\n"
-    @pp.handle text, cd
+    @pp.handle_directive '', 'x', 'y', code_object
 
-    assert_equal '', text
-    assert_equal 'y', cd.metadata['x']
+    assert_equal 'y', code_object.metadata['x']
 
-    cd.metadata.clear
-    text = "# :x: y\n"
+    code_object.metadata.clear
 
-    @pp.handle text do |directive, param|
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       false
     end
 
-    assert_equal "# :x: y\n", text
-    assert_empty cd.metadata
+    assert_equal ":x: y\n", result
+    assert_empty code_object.metadata
 
-    text = "# :x: y\n"
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
+      ''
+    end
+
+    assert_equal '', result
+    assert_empty code_object.metadata
+  end
+
+  def test_handle_directive_startdoc
+    code_object = RDoc::CodeObject.new
+    code_object.stop_doc
+    code_object.force_documentation = false
+
+    @pp.handle_directive '', 'startdoc', nil, code_object
+
+    assert code_object.document_self
+    assert code_object.document_children
+    assert code_object.force_documentation
+  end
+
+  def test_handle_directive_stopdoc
+    code_object = RDoc::CodeObject.new
+
+    @pp.handle_directive '', 'stopdoc', nil, code_object
+
+    refute code_object.document_self
+    refute code_object.document_children
+  end
+
+  def test_handle_directive_title
+    @pp.options = RDoc::Options.new
+
+    @pp.handle_directive '', 'title', 'T'
+
+    assert_equal 'T', @pp.options.title
+  end
+
+  def test_handle_directive_unhandled
+    code_object = RDoc::CodeObject.new
+
+    @pp.handle_directive '', 'x', 'y', code_object
+
+    assert_equal 'y', code_object.metadata['x']
+
+    code_object.metadata.clear
+
+    @pp.handle_directive '', 'x', '', code_object
+
+    assert_includes code_object.metadata, 'x'
+  end
+
+  def test_handle_directive_unhandled_block
+    code_object = RDoc::CodeObject.new
+
+    @pp.handle_directive '', 'x', 'y', code_object do
+      false
+    end
+
+    assert_empty code_object.metadata
+
+    @pp.handle_directive '', 'x', 'y', code_object do
+      nil
+    end
+
+    assert_equal 'y', code_object.metadata['x']
 
-    @pp.handle text do |directive, param|
+    code_object.metadata.clear
+
+    @pp.handle_directive '', 'x', 'y', code_object do
       ''
     end
 
-    assert_equal "", text
-    assert_empty cd.metadata
+    assert_empty code_object.metadata
+  end
+
+  def test_handle_directive_yield
+    method = RDoc::AnyMethod.new nil, 'm'
+    method.params = 'index, &block'
+
+    @pp.handle_directive '', 'yield', 'item', method
+
+    assert_equal 'item', method.block_params
+    assert_equal 'index', method.params
+  end
+
+  def test_handle_directive_yield_block_param
+    method = RDoc::AnyMethod.new nil, 'm'
+    method.params = '&block'
+
+    @pp.handle_directive '', 'yield', 'item', method
+
+    assert_equal 'item', method.block_params
+    assert_empty method.params
+  end
+
+  def test_handle_directive_yield_no_context
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'yield', 'item', method
+
+    assert_equal 'item', method.block_params
+  end
+
+  def test_handle_directive_yields
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'yields', 'item', method
+
+    assert_equal 'item', method.block_params
   end
 
 end
diff --git a/test/rdoc/test_rdoc_markup_to_html.rb b/test/rdoc/test_rdoc_markup_to_html.rb
index b43adf1560..9c26c00906 100644
--- a/test/rdoc/test_rdoc_markup_to_html.rb
+++ b/test/rdoc/test_rdoc_markup_to_html.rb
@@ -306,6 +306,14 @@ class TestRDocMarkupToHtml < RDoc::Markup::FormatterTestCase
                  @to.gen_url('link:example', 'example')
   end
 
+  def test_handle_special_HYPERLINK_link
+    special = RDoc::Markup::Special.new 0, 'link:README.txt'
+
+    link = @to.handle_special_HYPERLINK special
+
+    assert_equal '<a href="README.txt">README.txt</a>', link
+  end
+
   def test_list_verbatim_2
     str = "* one\n    verb1\n    verb2\n* two\n"
 
diff --git a/test/rdoc/test_rdoc_markup_to_html_crossref.rb b/test/rdoc/test_rdoc_markup_to_html_crossref.rb
index 8c97941727..4611e45309 100644
--- a/test/rdoc/test_rdoc_markup_to_html_crossref.rb
+++ b/test/rdoc/test_rdoc_markup_to_html_crossref.rb
@@ -10,159 +10,86 @@ class TestRDocMarkupToHtmlCrossref < XrefTestCase
   def setup
     super
 
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'index.html', @c1, true
+    @to = RDoc::Markup::ToHtmlCrossref.new 'index.html', @c1, true
   end
 
-  def assert_ref(path, ref)
-    assert_equal "\n<p><a href=\"#{path}\">#{ref}</a></p>\n", @xref.convert(ref)
-  end
+  def test_convert_CROSSREF
+    result = @to.convert 'C1'
 
-  def refute_ref(body, ref)
-    assert_equal "\n<p>#{body}</p>\n", @xref.convert(ref)
+    assert_equal "\n<p><a href=\"C1.html\">C1</a></p>\n", result
   end
 
-  def test_handle_special_CROSSREF_C2
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C2.html', @c2, true
-
-    refute_ref '#m', '#m'
+  def test_convert_HYPERLINK_rdoc_ref
+    result = @to.convert 'rdoc-ref:C1'
 
-    assert_ref '../C1.html#method-c-m', 'C1::m'
-    assert_ref '../C2/C3.html', 'C2::C3'
-    assert_ref '../C2/C3.html#method-i-m', 'C2::C3#m'
-    assert_ref '../C2/C3/H1.html', 'C3::H1'
-    assert_ref '../C4.html', 'C4'
-
-    assert_ref '../C3/H2.html', 'C3::H2'
-    refute_ref 'H1', 'H1'
+    assert_equal "\n<p><a href=\"C1.html\">C1</a></p>\n", result
   end
 
-  def test_handle_special_CROSSREF_C2_C3
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C2/C3.html', @c2_c3, true
-
-    assert_ref '../../C2/C3.html#method-i-m', '#m'
-
-    assert_ref '../../C2/C3.html', 'C3'
-    assert_ref '../../C2/C3.html#method-i-m', 'C3#m'
-
-    assert_ref '../../C2/C3/H1.html', 'H1'
-    assert_ref '../../C2/C3/H1.html', 'C3::H1'
-
-    assert_ref '../../C4.html', 'C4'
-
-    assert_ref '../../C3/H2.html', 'C3::H2'
+  def test_handle_special_CROSSREF
+    assert_equal "<a href=\"C2/C3.html\">C2::C3</a>", SPECIAL('C2::C3')
   end
 
-  def test_handle_special_CROSSREF_C3
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C3.html', @c3, true
-
-    assert_ref '../C3.html', 'C3'
-
-    refute_ref '#m',   '#m'
-    refute_ref 'C3#m', 'C3#m'
-
-    assert_ref '../C3/H1.html', 'H1'
-
-    assert_ref '../C3/H1.html', 'C3::H1'
-    assert_ref '../C3/H2.html', 'C3::H2'
-
-    assert_ref '../C4.html', 'C4'
-  end
-
-  def test_handle_special_CROSSREF_C4
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C4.html', @c4, true
+  def test_handle_special_CROSSREF_show_hash_false
+    @to.show_hash = false
 
-    # C4 ref inside a C4 containing a C4 should resolve to the contained class
-    assert_ref '../C4/C4.html', 'C4'
+    assert_equal "<a href=\"C1.html#method-i-m\">m</a>",
+                 SPECIAL('#m')
   end
 
-  def test_handle_special_CROSSREF_C4_C4
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C4/C4.html', @c4_c4, true
+  def test_handle_special_HYPERLINK_rdoc
+    RDoc::TopLevel.new 'README.txt'
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2, true
 
-    # A C4 reference inside a C4 class contained within a C4 class should
-    # resolve to the inner C4 class.
-    assert_ref '../../C4/C4.html', 'C4'
-  end
+    link = @to.handle_special_HYPERLINK hyper 'C2::C3'
 
-  def test_handle_special_CROSSREF_class
-    assert_ref 'C1.html', 'C1'
-    refute_ref 'H1', 'H1'
+    assert_equal '<a href="C2/C3.html">C2::C3</a>', link
 
-    assert_ref 'C2.html',       'C2'
-    assert_ref 'C2/C3.html',    'C2::C3'
-    assert_ref 'C2/C3/H1.html', 'C2::C3::H1'
+    link = @to.handle_special_HYPERLINK hyper 'C4'
 
-    assert_ref 'C3.html',    '::C3'
-    assert_ref 'C3/H1.html', '::C3::H1'
+    assert_equal '<a href="C4.html">C4</a>', link
 
-    assert_ref 'C4/C4.html', 'C4::C4'
-  end
+    link = @to.handle_special_HYPERLINK hyper 'README.txt'
 
-  def test_handle_special_CROSSREF_file
-    assert_ref 'xref_data_rb.html', 'xref_data.rb'
+    assert_equal '<a href="README_txt.html">README.txt</a>', link
   end
 
-  def test_handle_special_CROSSREF_method
-    refute_ref 'm', 'm'
-    assert_ref 'C1.html#method-i-m', '#m'
-    assert_ref 'C1.html#method-c-m', '::m'
-
-    assert_ref 'C1.html#method-i-m', 'C1#m'
-    assert_ref 'C1.html#method-c-m', 'C1.m'
-    assert_ref 'C1.html#method-c-m', 'C1::m'
+  def test_handle_special_TIDYLINK_rdoc
+    RDoc::TopLevel.new 'README.txt'
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2, true
 
-    assert_ref 'C1.html#method-i-m', 'C1#m'
-    assert_ref 'C1.html#method-i-m', 'C1#m()'
-    assert_ref 'C1.html#method-i-m', 'C1#m(*)'
+    link = @to.handle_special_TIDYLINK tidy 'C2::C3'
 
-    assert_ref 'C1.html#method-c-m', 'C1.m'
-    assert_ref 'C1.html#method-c-m', 'C1.m()'
-    assert_ref 'C1.html#method-c-m', 'C1.m(*)'
+    assert_equal '<a href="C2/C3.html">tidy</a>', link
 
-    assert_ref 'C1.html#method-c-m', 'C1::m'
-    assert_ref 'C1.html#method-c-m', 'C1::m()'
-    assert_ref 'C1.html#method-c-m', 'C1::m(*)'
+    link = @to.handle_special_TIDYLINK tidy 'C4'
 
-    assert_ref 'C2/C3.html#method-i-m', 'C2::C3#m'
+    assert_equal '<a href="C4.html">tidy</a>', link
 
-    assert_ref 'C2/C3.html#method-i-m', 'C2::C3.m'
+    link = @to.handle_special_TIDYLINK tidy 'README.txt'
 
-    # TODO stop escaping - HTML5 allows anything but space
-    assert_ref 'C2/C3/H1.html#method-i-m-3F', 'C2::C3::H1#m?'
-
-    assert_ref 'C2/C3.html#method-i-m', '::C2::C3#m'
-    assert_ref 'C2/C3.html#method-i-m', '::C2::C3#m()'
-    assert_ref 'C2/C3.html#method-i-m', '::C2::C3#m(*)'
+    assert_equal '<a href="README_txt.html">tidy</a>', link
   end
 
-  def test_handle_special_CROSSREF_no_ref
-    assert_equal '', @xref.convert('')
-
-    refute_ref 'bogus', 'bogus'
-    refute_ref 'bogus', '\bogus'
-    refute_ref '\bogus', '\\\bogus'
-
-    refute_ref '#n',    '\#n'
-    refute_ref '#n()',  '\#n()'
-    refute_ref '#n(*)', '\#n(*)'
+  def test_link
+    assert_equal 'n', @to.link('n', 'n')
 
-    refute_ref 'C1',   '\C1'
-    refute_ref '::C3', '\::C3'
+    assert_equal '<a href="C1.html#method-c-m">m</a>', @to.link('m', 'm')
+  end
 
-    refute_ref '::C3::H1#n',    '::C3::H1#n'
-    refute_ref '::C3::H1#n(*)', '::C3::H1#n(*)'
-    refute_ref '::C3::H1#n',    '\::C3::H1#n'
+  def SPECIAL text
+    @to.handle_special_CROSSREF special text
   end
 
-  def test_handle_special_CROSSREF_show_hash_false
-    @xref.show_hash = false
+  def hyper reference
+    RDoc::Markup::Special.new 0, "rdoc-ref:#{reference}"
+  end
 
-    assert_equal "\n<p><a href=\"C1.html#method-i-m\">m</a></p>\n",
-                 @xref.convert('#m')
+  def special text
+    RDoc::Markup::Special.new 0, text
   end
 
-  def test_handle_special_CROSSREF_special
-    assert_equal "\n<p><a href=\"C2/C3.html\">C2::C3</a>;method(*)</p>\n",
-                 @xref.convert('C2::C3;method(*)')
+  def tidy reference
+    RDoc::Markup::Special.new 0, "{tidy}[rdoc-ref:#{reference}]"
   end
 
 end
diff --git a/test/rdoc/test_rdoc_parser_ruby.rb b/test/rdoc/test_rdoc_parser_ruby.rb
index 4904d5dfca..6086b3ec13 100644
--- a/test/rdoc/test_rdoc_parser_ruby.rb
+++ b/test/rdoc/test_rdoc_parser_ruby.rb
@@ -313,22 +313,6 @@ class C; end
                  comment
   end
 
-  def test_look_for_directives_in_enddoc
-    util_parser ""
-
-    @parser.look_for_directives_in @top_level, "# :enddoc:\n"
-
-    assert @top_level.done_documenting
-  end
-
-  def test_look_for_directives_in_main
-    util_parser ""
-
-    @parser.look_for_directives_in @top_level, "# :main: new main page\n"
-
-    assert_equal 'new main page', @options.main_page
-  end
-
   def test_look_for_directives_in_method
     util_parser ""
 
@@ -345,31 +329,6 @@ class C; end
     assert_equal "# :singleton-method: my_method\n", comment
   end
 
-  def test_look_for_directives_in_startdoc
-    util_parser ""
-
-    @top_level.stop_doc
-    assert !@top_level.document_self
-    assert !@top_level.document_children
-
-    @parser.look_for_directives_in @top_level, "# :startdoc:\n"
-
-    assert @top_level.document_self
-    assert @top_level.document_children
-  end
-
-  def test_look_for_directives_in_stopdoc
-    util_parser ""
-
-    assert @top_level.document_self
-    assert @top_level.document_children
-
-    @parser.look_for_directives_in @top_level, "# :stopdoc:\n"
-
-    assert !@top_level.document_self
-    assert !@top_level.document_children
-  end
-
   def test_look_for_directives_in_section
     util_parser ""
 
@@ -384,14 +343,6 @@ class C; end
     assert_equal '', comment
   end
 
-  def test_look_for_directives_in_title
-    util_parser ""
-
-    @parser.look_for_directives_in @top_level, "# :title: new title\n"
-
-    assert_equal 'new title', @options.title
-  end
-
   def test_look_for_directives_in_unhandled
     util_parser ""
 
@@ -797,12 +748,7 @@ end
 
     @parser.parse_class @top_level, RDoc::Parser::Ruby::NORMAL, tk, comment
 
-    foo = @top_level.classes.first
-    assert_equal 'Foo', foo.full_name
-    assert_equal 'my class', foo.comment
-    assert_equal [@top_level], foo.in_files
-    assert_equal 0, foo.offset
-    assert_equal 1, foo.line
+    assert_empty @top_level.classes.first.comment
   end
 
   def test_parse_multi_ghost_methods
@@ -2227,6 +2173,45 @@ end
     assert_empty @top_level.comment
   end
 
+  def test_parse_top_level_statements_stopdoc_integration
+    content = <<-CONTENT
+# :stopdoc:
+
+class Example
+  def method_name
+  end
+end
+    CONTENT
+
+    util_parser content
+
+    @parser.parse_top_level_statements @top_level
+
+    assert_equal 1, @top_level.classes.length
+    assert_empty @top_level.modules
+
+    assert @top_level.find_module_named('Example').ignored?
+  end
+
+  # This tests parse_comment
+  def test_parse_top_level_statements_constant_nodoc_integration
+    content = <<-CONTENT
+class A
+  C = A # :nodoc:
+end
+    CONTENT
+
+    util_parser content
+
+    @parser.parse_top_level_statements @top_level
+
+    klass = @top_level.find_module_named('A')
+
+    c = klass.constants.first
+
+    assert_nil c.document_self, 'C should not be documented'
+  end
+
   def test_parse_yield_in_braces_with_parens
     klass = RDoc::NormalClass.new 'Foo'
     klass.parent = @top_level
diff --git a/test/rdoc/test_rdoc_ri_driver.rb b/test/rdoc/test_rdoc_ri_driver.rb
index da7d160047..e219993e57 100644
--- a/test/rdoc/test_rdoc_ri_driver.rb
+++ b/test/rdoc/test_rdoc_ri_driver.rb
@@ -5,6 +5,7 @@ require 'tmpdir'
 require 'fileutils'
 require 'stringio'
 require 'rdoc/ri/driver'
+require 'rdoc/rdoc'
 
 class TestRDocRIDriver < MiniTest::Unit::TestCase
 
@@ -223,7 +224,7 @@ class TestRDocRIDriver < MiniTest::Unit::TestCase
   def test_add_method_list_none
     out = @RM::Document.new
 
-    @driver.add_method_list out, nil, 'Class'
+    @driver.add_method_list out, [], 'Class'
 
     assert_equal @RM::Document.new, out
   end
@@ -249,6 +250,46 @@ class TestRDocRIDriver < MiniTest::Unit::TestCase
     assert_equal expected, @driver.classes
   end
 
+  def test_class_document
+    util_store
+
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    @cFoo.add_comment 'one', tl1
+    @cFoo.add_comment 'two', tl2
+    @store.save_class @cFoo
+
+    found = [
+      [@store, @store.load_class(@cFoo.full_name)]
+    ]
+
+    out = @driver.class_document @cFoo.full_name, found, [], []
+
+    expected = @RM::Document.new
+    @driver.add_class expected, 'Foo', []
+    @driver.add_includes expected, []
+    @driver.add_from expected, @store
+    expected << @RM::Rule.new(1)
+
+    doc = @RM::Document.new(@RM::Paragraph.new('one'))
+    doc.file = 'one.rb'
+    expected.push doc
+    expected << @RM::BlankLine.new
+    doc = @RM::Document.new(@RM::Paragraph.new('two'))
+    doc.file = 'two.rb'
+    expected.push doc
+
+    expected << @RM::Rule.new(1)
+    expected << @RM::Heading.new(1, 'Instance methods:')
+    expected << @RM::BlankLine.new
+    expected << @RM::Verbatim.new('inherit')
+    expected << @RM::Verbatim.new('override')
+    expected << @RM::BlankLine.new
+
+    assert_equal expected, out
+  end
+
   def test_complete
     store = RDoc::RI::Store.new @home_ri
     store.cache[:ancestors] = {
@@ -633,8 +674,24 @@ Foo::Bar#bother
   def test_list_methods_matching
     util_store
 
-    assert_equal %w[Foo::Bar#attr Foo::Bar#blah Foo::Bar#bother Foo::Bar::new],
-                 @driver.list_methods_matching('Foo::Bar.')
+    assert_equal %w[
+        Foo::Bar#attr
+        Foo::Bar#blah
+        Foo::Bar#bother
+        Foo::Bar::new
+      ],
+      @driver.list_methods_matching('Foo::Bar.').sort
+  end
+
+  def test_list_methods_matching_inherit
+    util_multi_store
+
+    assert_equal %w[
+        Bar#baz
+        Bar#inherit
+        Bar#override
+      ],
+      @driver.list_methods_matching('Bar.').sort
   end
 
   def test_list_methods_matching_regexp
@@ -805,6 +862,42 @@ Foo::Bar#bother
     assert_equal 'baz',      meth,  'Foo::Bar#baz method'
   end
 
+  def test_parse_name_special
+    specials = %w[
+      %
+      &
+      *
+      +
+      +@
+      -
+      -@
+      /
+      <
+      <<
+      <=
+      <=>
+      ==
+      ===
+      =>
+      =~
+      >
+      >>
+      []
+      []=
+      ^
+      `
+      |
+      ~
+      ~@
+    ]
+
+    specials.each do |special|
+      parsed = @driver.parse_name special
+
+      assert_equal ['', '.', special], parsed
+    end
+  end
+
   def _test_setup_pager # this test doesn't do anything anymore :(
     @driver.use_stdout = false
 
@@ -864,29 +957,28 @@ Foo::Bar#bother
 
   def util_multi_store
     util_store
+
     @store1 = @store
 
+    @top_level = RDoc::TopLevel.new 'file.rb'
+
     @home_ri2 = "#{@home_ri}2"
     @store2 = RDoc::RI::Store.new @home_ri2
 
     # as if seen in a namespace like class Ambiguous::Other
-    @mAmbiguous = RDoc::NormalModule.new 'Ambiguous'
+    @mAmbiguous = @top_level.add_module RDoc::NormalModule, 'Ambiguous'
 
-    @cFoo = RDoc::NormalClass.new 'Foo'
+    @cFoo = @top_level.add_class RDoc::NormalClass, 'Foo'
 
-    @cBar = RDoc::NormalClass.new 'Bar'
-    @cBar.superclass = 'Foo'
-    @cFoo_Baz = RDoc::NormalClass.new 'Baz'
-    @cFoo_Baz.parent = @cFoo
+    @cBar = @top_level.add_class RDoc::NormalClass, 'Bar', 'Foo'
+    @cFoo_Baz = @cFoo.add_class RDoc::NormalClass, 'Baz'
 
-    @baz = RDoc::AnyMethod.new nil, 'baz'
+    @baz = @cBar.add_method RDoc::AnyMethod.new(nil, 'baz')
     @baz.record_location @top_level
-    @cBar.add_method @baz
 
-    @override = RDoc::AnyMethod.new nil, 'override'
+    @override = @cBar.add_method RDoc::AnyMethod.new(nil, 'override')
     @override.comment = 'must be displayed'
     @override.record_location @top_level
-    @cBar.add_method @override
 
     @store2.save_class @mAmbiguous
     @store2.save_class @cBar
@@ -898,6 +990,8 @@ Foo::Bar#bother
     @store2.save_cache
 
     @driver.stores = [@store1, @store2]
+
+    RDoc::RDoc.reset
   end
 
   def util_store
@@ -905,53 +999,42 @@ Foo::Bar#bother
 
     @top_level = RDoc::TopLevel.new 'file.rb'
 
-    @cFoo       = RDoc::NormalClass.new 'Foo'
-    @mInc       = RDoc::NormalModule.new 'Inc'
-    @cAmbiguous = RDoc::NormalClass.new 'Ambiguous'
+    @cFoo = @top_level.add_class RDoc::NormalClass, 'Foo'
+    @mInc = @top_level.add_module RDoc::NormalModule, 'Inc'
+    @cAmbiguous = @top_level.add_class RDoc::NormalClass, 'Ambiguous'
 
     doc = @RM::Document.new @RM::Paragraph.new('Include thingy')
-
-    @cFooInc = RDoc::Include.new 'Inc', doc
+    @cFooInc = @cFoo.add_include RDoc::Include.new('Inc', doc)
     @cFooInc.record_location @top_level
-    @cFoo.add_include @cFooInc
 
-    @cFoo_Bar = RDoc::NormalClass.new 'Bar'
-    @cFoo_Bar.parent = @cFoo
+    @cFoo_Bar = @cFoo.add_class RDoc::NormalClass, 'Bar'
 
-    @blah = RDoc::AnyMethod.new nil, 'blah'
+    @blah = @cFoo_Bar.add_method RDoc::AnyMethod.new(nil, 'blah')
     @blah.call_seq = "blah(5) => 5\nblah(6) => 6\n"
     @blah.record_location @top_level
 
-    @bother = RDoc::AnyMethod.new nil, 'bother'
+    @bother = @cFoo_Bar.add_method RDoc::AnyMethod.new(nil, 'bother')
     @bother.block_params = "stuff"
     @bother.params = "(things)"
     @bother.record_location @top_level
 
-    @new  = RDoc::AnyMethod.new nil, 'new'
+    @new = @cFoo_Bar.add_method RDoc::AnyMethod.new nil, 'new'
     @new.record_location @top_level
     @new.singleton = true
 
-    @cFoo_Bar.add_method @blah
-    @cFoo_Bar.add_method @bother
-    @cFoo_Bar.add_method @new
-
-    @attr = RDoc::Attr.new nil, 'attr', 'RW', ''
+    @attr = @cFoo_Bar.add_attribute RDoc::Attr.new nil, 'attr', 'RW', ''
     @attr.record_location @top_level
 
-    @cFoo_Bar.add_attribute @attr
-
-    @cFoo_Baz = RDoc::NormalClass.new 'Baz'
-    @cFoo_Baz.parent = @cFoo
+    @cFoo_Baz = @cFoo.add_class RDoc::NormalClass, 'Baz'
+    @cFoo_Baz.record_location @top_level
 
-    @inherit = RDoc::AnyMethod.new nil, 'inherit'
+    @inherit = @cFoo.add_method RDoc::AnyMethod.new(nil, 'inherit')
     @inherit.record_location @top_level
-    @cFoo.add_method @inherit
 
     # overriden by Bar in multi_store
-    @overriden = RDoc::AnyMethod.new nil, 'override'
+    @overriden = @cFoo.add_method RDoc::AnyMethod.new(nil, 'override')
     @overriden.comment = 'must not be displayed'
     @overriden.record_location @top_level
-    @cFoo.add_method @overriden
 
     @store.save_class @cFoo
     @store.save_class @cFoo_Bar
@@ -970,6 +1053,8 @@ Foo::Bar#bother
     @store.save_cache
 
     @driver.stores = [@store]
+
+    RDoc::RDoc.reset
   end
 
 end
diff --git a/test/rdoc/xref_test_case.rb b/test/rdoc/xref_test_case.rb
index 00c6e8e09d..a001700d3b 100644
--- a/test/rdoc/xref_test_case.rb
+++ b/test/rdoc/xref_test_case.rb
@@ -43,6 +43,11 @@ class XrefTestCase < MiniTest::Unit::TestCase
     @c2_b  = @c2.method_list.first
 
     @c2_c3 = @xref_data.find_module_named 'C2::C3'
+    @c2_c3_m = @c2_c3.method_list.first # C2::C3#m
+
+    @c2_c3_h1 = @xref_data.find_module_named 'C2::C3::H1'
+    @c2_c3_h1_meh = @c2_c3_h1.method_list.first # C2::C3::H1#m?
+
     @c3    = @xref_data.find_module_named 'C3'
     @c4    = @xref_data.find_module_named 'C4'
     @c4_c4 = @xref_data.find_module_named 'C4::C4'