From: Tom Cloyd <tomcloyd@...>
Date: 2008-03-17T12:23:42+09:00
Subject: Re: argh! more undocumented mysteries: to_yaml

James Gray wrote:
> On Mar 16, 2008, at 6:56 PM, James Britt wrote:
>
>> Unfortunately, the conventional description for creating ri and rdoc 
>> for ruby, and the way the Ruby source code installation handles it, 
>> is to simply process the entire source folder.  More and more files 
>> have been added to .document files, with the default ri and rdoc 
>> output showing, for example, to_yaml as a method of Array.  So,
>>
>>  $ ri Array
>>
>> can be misleading.
>>
>> Basically, what is now appearing on ruby-doc.org are the results of 
>> the canonical rdoc'ing of the Ruby source.
>
> The main issue though is just that ruby-doc.org should only show core 
> documentation in that section though, right?
>
> Surely we could script that.  What happens if we replace the .document 
> files in lib/ and ext/ with empty files before we build the docs, or 
> just erase those two directories before we build?
>
> The standard library documentation is build by an altogether different 
> process Gavin Kistner manages (or at least did), right?
>
> I'm happy to help if I can.  Just let me know if you need anything.
>
> James Edward Gray II
>
>
>
James,

"The main issue though is just that ruby-doc.org should only show core 
documentation in that section though, right? "

Oh yes! Right on-message. I'm delighted to see that this whole thread 
just may result in a better documentation process and product. I'm 
grateful that some of the first citizens of the ruby community are 
paying attention. Very grateful.

Experience and expert knowledge makes us blind. But I don't have that 
experience, so maybe, just maybe, my distress about this issue will make 
Ruby and its documentation more accessible for the rising tide of people 
newly interested in this wonderful language. I hope so. That'd be a huge 
payoff, relative to anything else I might possibly contribute to the 
community.

This whole matter reminds me of a virtuous practice from the other major 
technical involvement I have with computers: building websites. We are 
well advised, in that domain, to invite the naive to interface with our 
products, because they will show us design flaws we blindly fly right 
past. This procedure really works, and really does produce major 
improvements in our product and its utility to consumers.

Carry on...

t.

-- 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog) 
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~