rdoc 2.5.11 → 3.0

data/lib/rdoc/markup/attribute_manager.rb

@@ -15,9 +15,12 @@ class RDoc::Markup::AttributeManager
   # optimistic
   #++
 
-  A_PROTECT  = 004 # :nodoc:
+  A_PROTECT = 004 # :nodoc:
 
-  PROTECT_ATTR  = A_PROTECT.chr # :nodoc:
+  ##
+  # Special mask character to prevent inline markup handling
+
+  PROTECT_ATTR = A_PROTECT.chr # :nodoc:
 
   ##
   # This maps delimiters that occur around words (such as *bold* or +tt+)
@@ -56,7 +59,7 @@ class RDoc::Markup::AttributeManager
   def initialize
     @html_tags = {}
     @matching_word_pairs = {}
-    @protectable = %w[<\\]
+    @protectable = %w[<]
     @special = {}
     @word_pair_map = {}
 
@@ -79,12 +82,19 @@ class RDoc::Markup::AttributeManager
     RDoc::Markup::AttrChanger.new turn_on, turn_off
   end
 
-  def change_attribute(current, new)
+  ##
+  # Changes the current attribute from +current+ to +new+
+
+  def change_attribute current, new
     diff = current ^ new
     attribute(new & diff, current & diff)
   end
 
-  def changed_attribute_by_name(current_set, new_set)
+  ##
+  # Used by the tests to change attributes by name from +current_set+ to
+  # +new_set+
+
+  def changed_attribute_by_name current_set, new_set
     current = new = 0
     current_set.each do |name|
       current |= RDoc::Markup::Attribute.bitmap_for(name)
@@ -97,6 +107,9 @@ class RDoc::Markup::AttributeManager
     change_attribute(current, new)
   end
 
+  ##
+  # Copies +start_pos+ to +end_pos+ from the current string
+
   def copy_string(start_pos, end_pos)
     res = @str[start_pos...end_pos]
     res.gsub!(/\000/, '')
@@ -164,6 +177,9 @@ class RDoc::Markup::AttributeManager
   # Escapes special sequences of text to prevent conversion to RDoc
 
   def mask_protected_sequences
+    # protect __send__, __FILE__, etc.
+    @str.gsub!(/__([a-z]+)__/i,
+      "_#{PROTECT_ATTR}_#{PROTECT_ATTR}\\1_#{PROTECT_ATTR}_#{PROTECT_ATTR}")
     @str.gsub!(/\\([#{Regexp.escape @protectable.join('')}])/,
                "\\1#{PROTECT_ATTR}")
   end
@@ -262,10 +278,12 @@ class RDoc::Markup::AttributeManager
     end
   end
 
+  ##
+  # Splits the string into chunks by attribute change
+
   def split_into_flow
     res = []
     current_attr = 0
-    str = ""
 
     str_len = @str.length
 

data/lib/rdoc/markup/blank_line.rb

@@ -1,12 +1,20 @@
 ##
-# An empty line
+# An empty line.  This class is a singleton.
 
 class RDoc::Markup::BlankLine
 
-  def == other # :nodoc:
-    self.class == other.class
+  @instance = new
+
+  ##
+  # RDoc::Markup::BlankLine is a singleton
+
+  def self.new
+    @instance
   end
 
+  ##
+  # Calls #accept_blank_line on +visitor+
+
   def accept visitor
     visitor.accept_blank_line self
   end

data/lib/rdoc/markup/document.rb

@@ -39,6 +39,9 @@ class RDoc::Markup::Document
     self.class == other.class and @parts == other.parts
   end
 
+  ##
+  # Runs this document and all its #items through +visitor+
+
   def accept visitor
     visitor.start_accepting
 
@@ -49,6 +52,9 @@ class RDoc::Markup::Document
     visitor.end_accepting
   end
 
+  ##
+  # Does this document have no parts?
+
   def empty?
     @parts.empty?
   end

data/lib/rdoc/markup/formatter.rb

@@ -7,6 +7,10 @@ require 'rdoc/markup'
 
 class RDoc::Markup::Formatter
 
+  ##
+  # Tag for inline markup containing a +bit+ for the bitmask and the +on+ and
+  # +off+ triggers.
+
   InlineTag = Struct.new(:bit, :on, :off)
 
   ##
@@ -101,6 +105,9 @@ class RDoc::Markup::Formatter
     @in_tt > 0
   end
 
+  ##
+  # Turns on tags for +item+ on +res+
+
   def on_tags res, item
     attr_mask = item.turn_on
     return if attr_mask.zero?
@@ -113,6 +120,9 @@ class RDoc::Markup::Formatter
     end
   end
 
+  ##
+  # Turns off tags for +item+ on +res+
+
   def off_tags res, item
     attr_mask = item.turn_off
     return if attr_mask.zero?

data/lib/rdoc/markup/formatter_test_case.rb

@@ -4,14 +4,57 @@ require 'rdoc/markup/formatter'
 ##
 # Test case for creating new RDoc::Markup formatters.  See
 # test/test_rdoc_markup_to_*.rb for examples.
+#
+# This test case adds a variety of tests to your subclass when
+# #add_visitor_tests is called.  Most tests set up a scenario then call a
+# method you will provide to perform the assertion on the output.
+#
+# Your subclass must instantiate a visitor and assign it to <tt>@to</tt>.
+#
+# For example, test_accept_blank_line sets up a RDoc::Markup::BlockLine then
+# calls accept_blank_line on your visitor.  You are responsible for asserting
+# that the output is correct.
+#
+# Example:
+#
+#  class TestRDocMarkupToNewFormat < RDoc::Markup::FormatterTestCase
+#
+#    add_visitor_tests
+#
+#    def setup
+#      super
+#
+#      @to = RDoc::Markup::ToNewFormat.new
+#    end
+#
+#    def accept_blank_line
+#      assert_equal :junk, @to.res.join
+#    end
+#
+#    # ...
+#
+#  end
 
 class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
 
+  ##
+  # Call #setup when inheriting from this test case.
+  #
+  # Provides the following instance variables:
+  #
+  # +@m+::           RDoc::Markup.new
+  # +@RM+::          RDoc::Markup # to reduce typing
+  # +@bullet_list+:: @RM::List.new :BULLET, # ...
+  # +@label_list+::  @RM::List.new :LABEL, # ...
+  # +@lalpha_list+:: @RM::List.new :LALPHA, # ...
+  # +@note_list+::   @RM::List.new :NOTE, # ...
+  # +@number_list+:: @RM::List.new :NUMBER, # ...
+  # +@ualpha_list+:: @RM::List.new :UALPHA, # ...
+
   def setup
     super
 
     @m = RDoc::Markup.new
-    @am = RDoc::Markup::AttributeManager.new
     @RM = RDoc::Markup
 
     @bullet_list = @RM::List.new(:BULLET,
@@ -39,14 +82,25 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
       @RM::ListItem.new(nil, @RM::Paragraph.new('l2')))
   end
 
+  ##
+  # Call to add the visitor tests to your test case
+
   def self.add_visitor_tests
     self.class_eval do
+
+      ##
+      # Calls start_accepting which needs to verify startup state
+    
       def test_start_accepting
         @to.start_accepting
 
         start_accepting
       end
 
+      ##
+      # Calls end_accepting on your test case which needs to call
+      # <tt>@to.end_accepting</tt> and verify document generation
+    
       def test_end_accepting
         @to.start_accepting
         @to.res << 'hi'
@@ -54,6 +108,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         end_accepting
       end
 
+      ##
+      # Calls accept_blank_line
+
       def test_accept_blank_line
         @to.start_accepting
 
@@ -62,6 +119,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_blank_line
       end
 
+      ##
+      # Calls accept_heading with a level 5 RDoc::Markup::Heading
+
       def test_accept_heading
         @to.start_accepting
 
@@ -70,6 +130,79 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_heading
       end
 
+      ##
+      # Calls accept_heading_1 with a level 1 RDoc::Markup::Heading
+
+      def test_accept_heading_1
+        @to.start_accepting
+
+        @to.accept_heading @RM::Heading.new(1, 'Hello')
+
+        accept_heading_1
+      end
+
+      ##
+      # Calls accept_heading_2 with a level 2 RDoc::Markup::Heading
+
+      def test_accept_heading_2
+        @to.start_accepting
+
+        @to.accept_heading @RM::Heading.new(2, 'Hello')
+
+        accept_heading_2
+      end
+
+      ##
+      # Calls accept_heading_3 with a level 3 RDoc::Markup::Heading
+
+      def test_accept_heading_3
+        # HACK this doesn't belong here
+        skip "No String#chars, upgrade your ruby" unless ''.respond_to? :chars
+
+        @to.start_accepting
+
+        @to.accept_heading @RM::Heading.new(3, 'Hello')
+
+        accept_heading_3
+      end
+
+      ##
+      # Calls accept_heading_4 with a level 4 RDoc::Markup::Heading
+
+      def test_accept_heading_4
+        @to.start_accepting
+
+        @to.accept_heading @RM::Heading.new(4, 'Hello')
+
+        accept_heading_4
+      end
+
+      ##
+      # Calls accept_heading_b with a bold level 1 RDoc::Markup::Heading
+
+      def test_accept_heading_b
+        @to.start_accepting
+
+        @to.accept_heading @RM::Heading.new(1, '*Hello*')
+
+        accept_heading_b
+      end
+
+      ##
+      # Calls accept_heading_suppressed_crossref with a level 1
+      # RDoc::Markup::Heading containing a suppressed crossref
+
+      def test_accept_heading_suppressed_crossref # HACK to_html_crossref test
+        @to.start_accepting
+
+        @to.accept_heading @RM::Heading.new(1, '\\Hello')
+        
+        accept_heading_suppressed_crossref
+      end
+
+      ##
+      # Calls accept_paragraph
+
       def test_accept_paragraph
         @to.start_accepting
 
@@ -78,15 +211,80 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_paragraph
       end
 
+      ##
+      # Calls accept_paragraph_b with a RDoc::Markup::Paragraph containing
+      # bold words
+
+      def test_accept_paragraph_b
+        @to.start_accepting
+
+        @to.accept_paragraph @RM::Paragraph.new('reg <b>bold words</b> reg')
+
+        accept_paragraph_b
+      end
+
+      ##
+      # Calls accept_paragraph_i with a RDoc::Markup::Paragraph containing
+      # emphasized words
+
+      def test_accept_paragraph_i
+        @to.start_accepting
+
+        @to.accept_paragraph @RM::Paragraph.new('reg <em>italic words</em> reg')
+
+        accept_paragraph_i
+      end
+
+      ##
+      # Calls accept_paragraph_plus with a RDoc::Markup::Paragraph containing
+      # teletype words
+
+      def test_accept_paragraph_plus
+        @to.start_accepting
+
+        @to.accept_paragraph @RM::Paragraph.new('reg +teletype+ reg')
+
+        accept_paragraph_plus
+      end
+
+      ##
+      # Calls accept_paragraph_star with a RDoc::Markup::Paragraph containing
+      # bold words
+
+      def test_accept_paragraph_star
+        @to.start_accepting
+
+        @to.accept_paragraph @RM::Paragraph.new('reg *bold* reg')
+
+        accept_paragraph_star
+      end
+
+      ##
+      # Calls accept_paragraph_underscore with a RDoc::Markup::Paragraph
+      # containing emphasized words
+
+      def test_accept_paragraph_underscore
+        @to.start_accepting
+
+        @to.accept_paragraph @RM::Paragraph.new('reg _italic_ reg')
+
+        accept_paragraph_underscore
+      end
+
+      ##
+      # Calls accept_verbatim with a RDoc::Markup::Verbatim
+
       def test_accept_verbatim
         @to.start_accepting
 
-        @to.accept_verbatim @RM::Verbatim.new('  ', 'hi', "\n",
-                                              '  ', 'world', "\n")
+        @to.accept_verbatim @RM::Verbatim.new("hi\n", "  world\n")
 
         accept_verbatim
       end
 
+      ##
+      # Calls accept_raw with a RDoc::Markup::Raw
+
       def test_accept_raw
         @to.start_accepting
 
@@ -99,6 +297,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_raw
       end
 
+      ##
+      # Calls accept_rule with a RDoc::Markup::Rule
+
       def test_accept_rule
         @to.start_accepting
 
@@ -107,6 +308,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_rule
       end
 
+      ##
+      # Calls accept_list_item_start_bullet
+
       def test_accept_list_item_start_bullet
         @to.start_accepting
 
@@ -117,6 +321,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_start_bullet
       end
 
+      ##
+      # Calls accept_list_item_start_label
+
       def test_accept_list_item_start_label
         @to.start_accepting
 
@@ -127,6 +334,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_start_label
       end
 
+      ##
+      # Calls accept_list_item_start_lalpha
+
       def test_accept_list_item_start_lalpha
         @to.start_accepting
 
@@ -137,6 +347,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_start_lalpha
       end
 
+      ##
+      # Calls accept_list_item_start_note
+
       def test_accept_list_item_start_note
         @to.start_accepting
 
@@ -147,6 +360,26 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_start_note
       end
 
+      ##
+      # Calls accept_list_item_start_note_2
+
+      def test_accept_list_item_start_note_2
+        list = @RM::List.new(:NOTE,
+                 @RM::ListItem.new('<tt>teletype</tt>',
+                   @RM::Paragraph.new('teletype description')))
+
+        @to.start_accepting
+
+        list.accept @to
+
+        @to.end_accepting
+
+        accept_list_item_start_note_2
+      end
+
+      ##
+      # Calls accept_list_item_start_number
+
       def test_accept_list_item_start_number
         @to.start_accepting
 
@@ -157,6 +390,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_start_number
       end
 
+      ##
+      # Calls accept_list_item_start_ualpha
+
       def test_accept_list_item_start_ualpha
         @to.start_accepting
 
@@ -167,6 +403,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_start_ualpha
       end
 
+      ##
+      # Calls accept_list_item_end_bullet
+
       def test_accept_list_item_end_bullet
         @to.start_accepting
 
@@ -179,6 +418,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_end_bullet
       end
 
+      ##
+      # Calls accept_list_item_end_label
+
       def test_accept_list_item_end_label
         @to.start_accepting
 
@@ -191,6 +433,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_end_label
       end
 
+      ##
+      # Calls accept_list_item_end_lalpha
+
       def test_accept_list_item_end_lalpha
         @to.start_accepting
 
@@ -203,6 +448,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_end_lalpha
       end
 
+      ##
+      # Calls accept_list_item_end_note
+
       def test_accept_list_item_end_note
         @to.start_accepting
 
@@ -215,6 +463,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_end_note
       end
 
+      ##
+      # Calls accept_list_item_end_number
+
       def test_accept_list_item_end_number
         @to.start_accepting
 
@@ -227,6 +478,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_end_number
       end
 
+      ##
+      # Calls accept_list_item_end_ualpha
+
       def test_accept_list_item_end_ualpha
         @to.start_accepting
 
@@ -239,6 +493,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_item_end_ualpha
       end
 
+      ##
+      # Calls accept_list_start_bullet
+
       def test_accept_list_start_bullet
         @to.start_accepting
 
@@ -247,6 +504,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_start_bullet
       end
 
+      ##
+      # Calls accept_list_start_label
+
       def test_accept_list_start_label
         @to.start_accepting
 
@@ -255,6 +515,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_start_label
       end
 
+      ##
+      # Calls accept_list_start_lalpha
+
       def test_accept_list_start_lalpha
         @to.start_accepting
 
@@ -263,6 +526,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_start_lalpha
       end
 
+      ##
+      # Calls accept_list_start_note
+
       def test_accept_list_start_note
         @to.start_accepting
 
@@ -271,6 +537,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_start_note
       end
 
+      ##
+      # Calls accept_list_start_number
+
       def test_accept_list_start_number
         @to.start_accepting
 
@@ -279,6 +548,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_start_number
       end
 
+      ##
+      # Calls accept_list_start_ualpha
+
       def test_accept_list_start_ualpha
         @to.start_accepting
 
@@ -287,6 +559,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_start_ualpha
       end
 
+      ##
+      # Calls accept_list_end_bullet
+
       def test_accept_list_end_bullet
         @to.start_accepting
 
@@ -297,6 +572,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_end_bullet
       end
 
+      ##
+      # Calls accept_list_end_label
+
       def test_accept_list_end_label
         @to.start_accepting
 
@@ -307,6 +585,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_end_label
       end
 
+      ##
+      # Calls accept_list_end_lalpha
+
       def test_accept_list_end_lalpha
         @to.start_accepting
 
@@ -317,6 +598,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_end_lalpha
       end
 
+      ##
+      # Calls accept_list_end_number
+
       def test_accept_list_end_number
         @to.start_accepting
 
@@ -327,6 +611,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_end_number
       end
 
+      ##
+      # Calls accept_list_end_note
+
       def test_accept_list_end_note
         @to.start_accepting
 
@@ -337,6 +624,9 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_list_end_note
       end
 
+      ##
+      # Calls accept_list_end_ulpha
+
       def test_accept_list_end_ualpha
         @to.start_accepting
 
@@ -346,6 +636,52 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
 
         accept_list_end_ualpha
       end
+
+      ##
+      # Calls list_nested with a two-level list
+
+      def test_list_nested
+        doc = @RM::Document.new(
+                @RM::List.new(:BULLET,
+                  @RM::ListItem.new(nil,
+                    @RM::Paragraph.new('l1'),
+                    @RM::List.new(:BULLET,
+                      @RM::ListItem.new(nil,
+                        @RM::Paragraph.new('l1.1')))),
+                  @RM::ListItem.new(nil,
+                    @RM::Paragraph.new('l2'))))
+
+        doc.accept @to
+
+        list_nested
+      end
+
+      ##
+      # Calls list_verbatim with a list containing a verbatim block
+
+      def test_list_verbatim # HACK overblown
+        doc = @RM::Document.new(
+                @RM::List.new(:BULLET,
+                  @RM::ListItem.new(nil,
+                    @RM::Paragraph.new('list', 'stuff'),
+                    @RM::BlankLine.new,
+                    @RM::Verbatim.new("* list\n",
+                                      "  with\n",
+                                      "\n",
+                                      "  second\n",
+                                      "\n",
+                                      "  1. indented\n",
+                                      "  2. numbered\n",
+                                      "\n",
+                                      "  third\n",
+                                      "\n",
+                                      "* second\n"))))
+
+        doc.accept @to
+
+        list_verbatim
+      end
+
     end
   end