# Rdoc markup question

**URL:** <https://www.ruby-forum.com/t/rdoc-markup-question/93258>\
**Category:** Ruby\
**Created:** [April 30, 2007, 4:54am UTC](https://www.ruby-forum.com/t/rdoc-markup-question/93258 "2007-04-30T04:54:01Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![pfharlock](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/f04885/32.png) [@pfharlock](https://www.ruby-forum.com/u/pfharlock)\
**Post date:** [April 30, 2007, 4:54am UTC](https://www.ruby-forum.com/t/rdoc-markup-question/93258/1 "2007-04-30T04:54:01Z")

</div>

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 “” and have the rdoc parser die on me.

Any suggestions?

Gary W.

---

<div class="post-metadata">

**Author:** ![pfharlock](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/f04885/32.png) [@pfharlock](https://www.ruby-forum.com/u/pfharlock)\
**Post date:** [April 30, 2007, 6:01am UTC](https://www.ruby-forum.com/t/rdoc-markup-question/93258/2 "2007-04-30T06:01:05Z")

</div>

On Apr 29, 8:52 pm, Gary W. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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-talk-google/browse\_frm/thread/9379ed6b1c907f17/82b5df7ee399b70d?#82b5df7ee399b70d](http://groups.google.com/group/ruby-talk-google/browse_frm/thread/9379ed6b1c907f17/82b5df7ee399b70d?#82b5df7ee399b70d)

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 “” and have the rdoc parser die on me.

Sounds like a bug to me. Please report it.

Regards,

Dan

---

<div class="post-metadata">

**Author:** ![pfharlock](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/f04885/32.png) [@pfharlock](https://www.ruby-forum.com/u/pfharlock)\
**Post date:** [April 30, 2007, 10:37pm UTC](https://www.ruby-forum.com/t/rdoc-markup-question/93258/3 "2007-04-30T22:37:53Z")

</div>

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

> Nope. I brought this up at  
> [http://groups.google.com/group/ruby-talk-google/browse\_frm/thread/](http://groups.google.com/group/ruby-talk-google/browse_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 W.

---

<div class="post-metadata">

**Author:** ![pfharlock](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/f04885/32.png) [@pfharlock](https://www.ruby-forum.com/u/pfharlock)\
**Post date:** [April 30, 2007, 10:54pm UTC](https://www.ruby-forum.com/t/rdoc-markup-question/93258/4 "2007-04-30T22:54:54Z")

</div>

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

> On Apr 29, 8:52 pm, Gary W. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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 “” 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=“” (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 ``` block: ```

# 

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

# some text

def method4  
end

# The line below is not OK because the handler for the :COMMENT

pattern

# is not defined:

# 

def method3  
end

end

Gary W.