From: James Britt <james.britt@...>
Date: 2008-03-17T08:56:50+09:00
Subject: Re: argh! more undocumented mysteries: to_yaml

Dave Thomas wrote:
> 
> On Mar 16, 2008, at 11:47 AM, James Britt wrote:
> 
>>
>> It appears that the Ruby source code includes .document files that 
>> direct which source files should be processed by rdoc
>>
>> What has happened is that there is no clear separation in the rdoc 
>> settings between core classes and standard lib.
>>
>> The Yaml source files get pulled in by rdoc along with several other 
>> std-lib files, as well as core files.  Rdoc stores what it finds and 
>> emits an aggregate result.  Since yaml alters core classes, the 
>> resulting rdoc falsely shows Array, String, etc as having to_yaml 
>> methods as if they were built into the original code.    There is no 
>> indication that those methods only exist if YAML is included.
> 
> James:
> 
> When you use all this stuff to build ruby-doc, why not override the 
> defaults so you can present the information differently?

I am looking into that.

It is not clear what would be a good approach to ensure that all the 
files get covered by rdoc, yet do not interfere with other files if they 
involve modifying other files, and still have proper "cluster" 
processing of sets of files that belong together (such as, say, the tk 
or REXML files).

One thought was to run rdoc over each file individually, and then 
reassembly the resulting pages.  Somehow.  The generation process is 
easy enough to automate.  I'm unsure though that the resulting files are 
not going to lose some essential cohesion (aside from the main index a 
bulk rdoc pass creates).


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.

James


> 
> 
> Regards
> 
> 
> Dave Thomas
> 
> 


-- 
James Britt

"Trying to port the desktop metaphor to the Web is like working
on how to fuel your car with hay because that is what horses eat."
    - Dare Obasanjo