Used rdoc -u to improve documentation

Author: drbrain

lib/rdoc/any_method.rb

@@ -25,8 +25,12 @@ class RDoc::AnyMethod < RDoc::MethodAttr
 
   include RDoc::TokenStream
 
-  def initialize(text, name)
-    super text, name
+  ##
+  # Creates a new AnyMethod with a token stream +text+ and +name+
+
+  def initialize text, name
+    super
+
     @dont_rename_initialize = false
     @token_stream           = nil
   end

lib/rdoc/constant.rb

@@ -42,6 +42,9 @@ def <=> other
     [parent_name, name] <=> [other.parent_name, other.name]
   end
 
+  ##
+  # Constants are equal when their #parent and #name is the same
+
   def == other
     self.class == other.class and
       @parent == other.parent and

lib/rdoc/generator/markup.rb

@@ -58,17 +58,20 @@ def cvs_url(url, full_path)
 
 class RDoc::AnyMethod
 
+  ##
+  # Maps RDoc::RubyToken classes to CSS class names
+
   STYLE_MAP = {
-    RDoc::RubyToken::TkCONSTANT => "ruby-constant",
-    RDoc::RubyToken::TkKW       => "ruby-keyword",
-    RDoc::RubyToken::TkIVAR     => "ruby-ivar",
-    RDoc::RubyToken::TkOp       => "ruby-operator",
-    RDoc::RubyToken::TkId       => "ruby-identifier",
-    RDoc::RubyToken::TkNode     => "ruby-node",
-    RDoc::RubyToken::TkCOMMENT  => "ruby-comment",
-    RDoc::RubyToken::TkREGEXP   => "ruby-regexp",
-    RDoc::RubyToken::TkSTRING   => "ruby-string",
-    RDoc::RubyToken::TkVal      => "ruby-value",
+    RDoc::RubyToken::TkCONSTANT => 'ruby-constant',
+    RDoc::RubyToken::TkKW       => 'ruby-keyword',
+    RDoc::RubyToken::TkIVAR     => 'ruby-ivar',
+    RDoc::RubyToken::TkOp       => 'ruby-operator',
+    RDoc::RubyToken::TkId       => 'ruby-identifier',
+    RDoc::RubyToken::TkNode     => 'ruby-node',
+    RDoc::RubyToken::TkCOMMENT  => 'ruby-comment',
+    RDoc::RubyToken::TkREGEXP   => 'ruby-regexp',
+    RDoc::RubyToken::TkSTRING   => 'ruby-string',
+    RDoc::RubyToken::TkVal      => 'ruby-value',
   }
 
   include RDoc::Generator::Markup

lib/rdoc/markup/attribute_manager.rb

@@ -79,12 +79,19 @@ def attribute(turn_on, turn_off)
     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 +104,9 @@ def changed_attribute_by_name(current_set, new_set)
     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/, '')
@@ -265,6 +275,9 @@ def display_attributes
     end
   end
 
+  ##
+  # Splits the string into chunks by attribute change
+
   def split_into_flow
     res = []
     current_attr = 0

lib/rdoc/markup/blank_line.rb

@@ -5,10 +5,16 @@ class RDoc::Markup::BlankLine
 
   @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

lib/rdoc/markup/document.rb

@@ -39,6 +39,9 @@ def == other # :nodoc:
     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 @@ def accept visitor
     visitor.end_accepting
   end
 
+  ##
+  # Does this document have no parts?
+
   def empty?
     @parts.empty?
   end

lib/rdoc/markup/formatter.rb

@@ -7,6 +7,10 @@
 
 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 @@ def in_tt?
     @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 @@ def on_tags res, item
     end
   end
 
+  ##
+  # Turns off tags for +item+ on +res+
+
   def off_tags res, item
     attr_mask = item.turn_off
     return if attr_mask.zero?

lib/rdoc/markup/formatter_test_case.rb

@@ -4,9 +4,43 @@
 ##
 # Test case for creating new RDoc::Markup formatters.  See
 # test/test_rdoc_markup_to_*.rb for examples.
+#
+# 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
 
@@ -38,7 +72,11 @@ def setup
       @RM::ListItem.new(nil, @RM::Paragraph.new('l2')))
   end
 
+  ##
+  # Call to add the visitor tests to your test case
+
   def self.add_visitor_tests
+    # :stopdoc:
     self.class_eval do
       def test_start_accepting
         @to.start_accepting
@@ -487,6 +525,7 @@ def test_list_verbatim # HACK overblown
 
         list_verbatim
       end
+    # :stopdoc:
     end
   end
 

lib/rdoc/markup/heading.rb

@@ -3,6 +3,9 @@
 
 class RDoc::Markup::Heading < Struct.new :level, :text
 
+  ##
+  # Calls #accept_heading on +wisitor+
+
   def accept visitor
     visitor.accept_heading self
   end

lib/rdoc/markup/inline.rb

@@ -15,6 +15,9 @@ class Attribute
     @@name_to_bitmap = { :_SPECIAL_ => SPECIAL }
     @@next_bitmap = 2
 
+    ##
+    # Returns a unique bit for +name+
+
     def self.bitmap_for(name)
       bitmap = @@name_to_bitmap[name]
       unless bitmap then
@@ -25,6 +28,9 @@ def self.bitmap_for(name)
       bitmap
     end
 
+    ##
+    # Returns a string reperesentation of +bitmap+
+
     def self.as_string(bitmap)
       return "none" if bitmap.zero?
       res = []
@@ -34,6 +40,9 @@ def self.as_string(bitmap)
       res.join(",")
     end
 
+    ##
+    # yields each attribute name in +bitmap+
+
     def self.each_name_of(bitmap)
       @@name_to_bitmap.each do |name, bit|
         next if bit == SPECIAL