I just did (quote from history command in tcsh)

   330  12:26   cd RUBY-STABLE-SNAPSHOT-BRAINS/
   331  12:26   ./bin/rdoc -o /home/hgs/public_html/ruby/RUBY_SNAPSHOT_RDOC

and got

/apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:230:in `convert_special': Unhandled special: Special: type=17, text="<!-- ... -->" (RuntimeError)
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:180:in `convert_flow'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:172:in `convert_flow'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:68:in `accept_paragraph'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/markup/simple_markup/fragments.rb:182:in `accept'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/markup/simple_markup/fragments.rb:165:in `accept'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/markup/simple_markup.rb:258:in `convert'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:246:in `markup'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:648:in `value_hash'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:634:in `write_on'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:1293:in `gen_into'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:1293:in `gen_into'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:1289:in `gen_into'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:1277:in `generate_html'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/generators/html_generator.rb:1197:in `generate'
        from /apps/hgs/RUBY-STABLE-SNAPSHOT-BRAINS/lib/ruby/1.8/rdoc/rdoc.rb:263:in `document'
        from ./bin/rdoc:63
brains hgs 332 %>

On starting to examine the code I see that vim highlighting is a bit
odd, and trace this to <<"\n" which looks like an unterminated here
document.

<patch>
 
--- ./lib/rdoc/markup/simple_markup/to_html.rb.orig	2003-12-01 07:12:48.000000000 +0000
+++ ./lib/rdoc/markup/simple_markup/to_html.rb	2006-07-20 13:23:40.548927000 +0100
@@ -82,7 +82,7 @@
     end
 
     def accept_list_start(am, fragment)
-      @res << html_list_name(fragment.type, true) <<"\n"
+      @res << html_list_name(fragment.type, true) << "\n"
       @in_list_entry.push false
     end
 
@@ -90,7 +90,7 @@
       if tag = @in_list_entry.pop
         @res << annotate(tag) << "\n"
       end
-      @res << html_list_name(fragment.type, false) <<"\n"
+      @res << html_list_name(fragment.type, false) << "\n"
     end
 
     def accept_list_item(am, fragment)

</patch>

But I can't see where the specials are set up so as to end up with 
unprocessable comments.

        Hugh