From: Gary Wright <gwtmp01@...>
Date: 2007-05-01T05:53:58+09:00
Subject: Re: rdoc markup question


On Apr 30, 2007, at 12:00 AM, Daniel Berger wrote:

> On Apr 29, 8:52 pm, Gary Wright <gwtm...@mac.com> wrote:
>> Similarly I also found that when I have XML strings in the comments
>> I can either use "\<!-- comment -->" and have the \ show up in the
>> comments
>> or have "<!-- comment -->" and have the rdoc parser die on me.
>
> Sounds like a bug to me. Please report it.

I've entered this into the tracker for rdoc (#10474):

In markup/simple_markup/inline.rb:

      add_special(/<!--(.*?)-->/, :COMMENT)

marks an XML comment to be given special handling but the method  
handle_special_COMMENT
is never defined.  This causes an unhandled exception when the HTML  
generator runs:

/opt/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:230:in  
`convert_special': Unhandled special: Special: type=17,
text="<!-- foo -->" (RuntimeError)

I'm not sure if the intent was to insert the XML comment into the  
generated XHTML or to
escape the comment so that it appeared as readable text.

The following code illustrates the problem:

class A
   # The line below is OK because it is processed as a <pre> block:
   #   <!-- comment -->
   def method1
   end

   # The line below is OK because it is protected by the \.
   # \<!-- comment-->
   def method2
   end


   # The line below is OK because it doesn't match any markup patterns
   # <foo>some text</foo>
   def method4
   end

   # The line below is not OK because the handler for the :COMMENT  
pattern
   # is not defined:
   # <!-- comment-->
   def method3
   end

end



Gary Wright