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

Tom Cloyd wrote:
> James Gray wrote:

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

And then what's left shows correctly under std-lib.


Though, ideally, there would be no distinction, and looking at the docs 
for any method or class, etc would simply tell you what, if anything, 
need be require'd.
>>
>> 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?

I believe it docs everything it finds.

(Side question: why are those .document files the way they are, if the 
results aren't what they should be?)

>>
>> The standard library documentation is build by an altogether different 
>> process Gavin Kistner manages (or at least did), right?

I sort of am the owner.  I need to spend more time with it so as to be a 
proper owner.

>>
>> I'm happy to help if I can.  Just let me know if you need anything.

Thank you very much.

Short term goal: a low-maintenance approach (e.g., it cannot break when 
cron does an svn up to get the newest source)  to passing rdoc over the 
source such that ruby-doc.org/core/* shows just the core, and 
ruby-doc.org/std-lib/*.  Cron'ed tasks that, after re-upping from svn, 
munge .document files, is a likely target.

Long-term: a way for everyone to run rdoc or its successor over the 
complete source tree and get a single set of docs that clearly indicate 
when something is core or not, and how to make things Just Work.

An ideal (to me, currently) end result would be a process that took 
atomic rdoc data and populated a database; API docs pages would then be 
generated from that database, allowing for interesting (and, I hope, 
useful) queries.

It would nice, for example, to easily see what libs, bundled with a 
standard Ruby distro, will alter String if included.

Or to have a Web page showing String docs, with ajazzy hooks to 
show/hide the results of including various modules (such as YAML)


-- 
James Britt

"I never dispute another person's delusions, just their facts."
   - Len Bullard