Improve documentation

Author: drbrain

lib/rdoc/markup/text_formatter_test_case.rb

@@ -1,14 +1,44 @@
 require 'rdoc/markup/formatter_test_case'
 
 ##
-# Test case for creating new RDoc::Markup formatters.  See
-# test_rdoc_markup_to_*.rb for examples.
+# Test case for creating new RDoc::Markup formatters.  See also
+# RDoc::Markup::FormatterTestCase
+#
+#
+# See test_rdoc_markup_to_rdoc.rb for a complete example.
+#
+# Example:
+#
+#  class TestRDocMarkupToNewTextFormat < RDoc::Markup::TextFormatterTestCase
+#
+#    add_visitor_tests
+#    add_text_tests
+#
+#    def setup
+#      super
+#
+#      @to = RDoc::Markup::ToNewTextFormat.new
+#    end
+#
+#    def accept_blank_line
+#      assert_equal :junk, @to.res.join
+#    end
+#
+#    # ...
+#
+#  end
 
 class RDoc::Markup::TextFormatterTestCase < RDoc::Markup::FormatterTestCase
 
+  ##
+  # Adds test cases to the calling TestCase.
+
   def self.add_text_tests
     self.class_eval do
 
+      ##
+      # Test case that calls <tt>@to.accept_heading</tt>
+
       def test_accept_heading_indent
         @to.start_accepting
         @to.indent = 3
@@ -17,6 +47,9 @@ def test_accept_heading_indent
         accept_heading_indent
       end
 
+      ##
+      # Test case that calls <tt>@to.accept_rule</tt>
+
       def test_accept_rule_indent
         @to.start_accepting
         @to.indent = 3
@@ -25,6 +58,9 @@ def test_accept_rule_indent
         accept_rule_indent
       end
 
+      ##
+      # Test case that calls <tt>@to.accept_verbatim</tt>
+
       def test_accept_verbatim_indent
         @to.start_accepting
         @to.indent = 2
@@ -33,6 +69,9 @@ def test_accept_verbatim_indent
         accept_verbatim_indent
       end
 
+      ##
+      # Test case that calls <tt>@to.accept_verbatim</tt> with a big indent
+
       def test_accept_verbatim_big_indent
         @to.start_accepting
         @to.indent = 2
@@ -41,6 +80,9 @@ def test_accept_verbatim_big_indent
         accept_verbatim_big_indent
       end
 
+      ##
+      # Test case that calls <tt>@to.accept_paragraph</tt> with an indent
+
       def test_accept_paragraph_indent
         @to.start_accepting
         @to.indent = 3
@@ -49,13 +91,21 @@ def test_accept_paragraph_indent
         accept_paragraph_indent
       end
 
+      ##
+      # Test case that calls <tt>@to.accept_paragraph</tt> with a long line
+
       def test_accept_paragraph_wrap
         @to.start_accepting
         @to.accept_paragraph @RM::Paragraph.new(('words ' * 30).strip)
 
         accept_paragraph_wrap
       end
 
+      ##
+      # Test case that calls <tt>@to.attributes</tt> with an escaped
+      # cross-reference.  If this test doesn't pass something may be very
+      # wrong.
+
       def test_attributes
         assert_equal 'Dog', @to.attributes("\\Dog")
       end