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

I certainly agree.

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

Yes, good point.  I'll try to do that with some existing libraries.

Cheers,
Gavin