From: Dave Thomas <dave@...>
Date: 2004-05-19T08:45:29+09:00
Subject: Re: RI for distribution


On May 18, 2004, at 17:20, Gavin Sinclair wrote:

> On Wednesday, May 19, 2004, 4:59:58 AM, why wrote:
>
>> Hi, everyone.
>
>> I'd like to start checking in some RDoc for a bunch of YAML modules.  
>> Am
>> I okay to add these files into the lib/.document file listing?  I'd 
>> like
>> to document every class in my set.  Is that overkill?
>
> In a sense it's overkill, but it doesn't matter; the more the merrier.
> Just make sure you provide a good introduction in the obvious place
> (or introduce a README file) so casual users can get the information
> they need quickly.

Gavin/Why:

I don't think this is in the spirit of the thing.

'ri' is for end users of packages, and so should really only document 
the classes and methods of interest to them. I wouldn't want to see 
internal classes included in the standard 'ri' set that comes with 
Ruby: I think this would only confuse things.

Also, when it comes to README files -- I think the best thing to do is 
to :include: them in the comment for your top-level class. That way 
people browsing the source can find them, and people using RDoc/ri will 
also be able to benefits from all that wisdom.


Cheers

Dave