From: Dave Thomas <dave@...>
Date: 2003-10-22T05:25:47+09:00
Subject: Re: RDoc and i18n


On Tuesday, Oct 21, 2003, at 15:21 US/Central, Austin Ziegler wrote:

> In general, I agree. However, there was a conversation on #ruby-talk
> a few weeks ago (where I started looking at this) that suggested
> that there are cases when the inline documentation is, well, too
> much. There are cases when RDoc makes really good API documentation,
> but doesn't work as well when you're reading the source itself. (The
> complaint was specifically about methods that are really self-
> documenting, such as #<=>.)
>

Would it be possible to come up with a specific example: I'm kinda slow 
today, and I'm havign a hard time seeing this.

> There's also no "clean" way to have RDoc help document the *use* of
> a library which may be different than documenting the pure API. This
> may help with some of that.
>

Could the file or class-level comment be used for this?

I'm not trying to quell requests for change here: I'm just trying to 
understand the need.

Cheers


Dave