Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Ruby > rdoc markup question

Reply
Thread Tools

rdoc markup question

 
 
Gary Wright
Guest
Posts: n/a
 
      04-30-2007
Is there a way to disable rdoc's automatic cross referencing of method
names? I've got a method named 'null' but I don't want every instance
of the word 'null' in the comments to be hyperlinked to the method
definition. I tried writing '\null' or 'n\ull' but then the backslash
shows up in the comments.

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.

Any suggestions?


Gary Wright




 
Reply With Quote
 
 
 
 
Daniel Berger
Guest
Posts: n/a
 
      04-30-2007
On Apr 29, 8:52 pm, Gary Wright <(E-Mail Removed)> wrote:
> Is there a way to disable rdoc's automatic cross referencing of method
> names? I've got a method named 'null' but I don't want every instance
> of the word 'null' in the comments to be hyperlinked to the method
> definition. I tried writing '\null' or 'n\ull' but then the backslash
> shows up in the comments.


Nope. I brought this up at
http://groups.google.com/group/ruby-...b5df7ee399b70d

I find it annoying, too.

> 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.

Regards,

Dan


 
Reply With Quote
 
 
 
 
Gary Wright
Guest
Posts: n/a
 
      04-30-2007

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

> On Apr 29, 8:52 pm, Gary Wright <(E-Mail Removed)> wrote:
>> Is there a way to disable rdoc's automatic cross referencing of
>> method
>> names? I've got a method named 'null' but I don't want every
>> instance
>> of the word 'null' in the comments to be hyperlinked to the method
>> definition. I tried writing '\null' or 'n\ull' but then the
>> backslash
>> shows up in the comments.

>
> Nope. I brought this up at
> http://groups.google.com/group/ruby-...se_frm/thread/
> 9379ed6b1c907f17/82b5df7ee399b70d?#82b5df7ee399b70d
>
> I find it annoying, too.


I read that thread. I think the default heuristic is ok. In the
thread you suggested an explicit syntax to trigger the cross-reference.
I'd suggest an explicit syntax to disable the cross-reference.

I could of course come up with a patch but even if adopted it would
take a while to propagate through the Ruby ecosystem. I was hoping
there was a trick or hack of some sort.

I see that this issue is actually entered into the the tracker for rdoc
as issue 9316. There are quite a few unresolved issues in the list...


Gary Wright




 
Reply With Quote
 
Gary Wright
Guest
Posts: n/a
 
      04-30-2007

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

> On Apr 29, 8:52 pm, Gary Wright <(E-Mail Removed)> 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




 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Better RDoc Inline Markup Intransition Ruby 11 09-05-2009 10:00 AM
Proper way to RDoc markup? Serg Koren Ruby 11 09-27-2008 06:29 PM
RDoc question: How do I make a link from the README file to aspecific RDOC Page Jesper Rønn-Jensen Ruby 4 02-22-2008 10:58 PM
RDoc markup Peter Marsh Ruby 2 06-12-2007 07:47 AM
RDoc::usage dies on markup in heading Stefan Lang Ruby 2 12-31-2004 10:19 AM



Advertisments