From: Dave Thomas <dave@...>
Date: 2007-01-01T23:29:49+09:00
Subject: Re: Question on rdoc, unwanted hyperlinked methods


On Dec 31, 2006, at 9:40 PM, Daniel Berger wrote:

> It's not clear in the documentation (Programming Ruby 2nd ed., p. 204)
> that this is what the behavior is, unless I've missed it.  I've always
> written Foo#test if I wanted a method explicitly hyperlinked,  
> because I
> thought you had to.  And, now that I see what the current behavior is,
> I think I would prefer that explicit hyperlinking be required.


The underlying philosophy of the RDoc markup is that it should be  
transparent. It was a reaction to JavaDoc, where you had to seriously  
mess with your comments to make them work with the documentation  
system. I wanted RDoc to be such that some third party reading the  
original source didn't know that the comments were in a format  
suitable for RDoc--I wanted the comments in the source to be written  
for humans, not for the documentation tool.

As a result, RDoc contains lots of heuristics. If it gets it wrong  
every now and then, I personally think that's an OK tradeoff.


Cheers


Dave