From: Daniel Berger <djberg96@...>
Date: 2007-01-04T01:00:06+09:00
Subject: Re: Question on rdoc, unwanted hyperlinked methods

Dave Thomas wrote:
> 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'm not familiar with JavaDoc, but I can imagine.

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

Except that, to me, having to write "Class#method" in order to force an
html link in RDoc doesn't strike me as being out of line with your
philosophy of transparency.  It's a standard way of referring to
instance methods these days, and it's quite readable IMO. No special
markup required.

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

I'm certainly not going to lose sleep over it.  It's a minor nit,
really.  I just happened to think that a minor bit of required
explicitness would generate better results without any real loss of
transparency.

Regards,

Dan