From: James Gray <james@...>
Date: 2008-03-18T01:33:10+09:00
Subject: Re: argh! more undocumented mysteries: to_yaml

On Mar 17, 2008, at 12:07 AM, James Britt wrote:

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

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?
>
> 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?)

Yeah, good point.  I just checked and you're right in that it must be  
ignoring them.

What about blowing away lib/ and ext/?  Does that work?

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

We should be sharing these great ideas with Eric Hodel, who has been  
revamping RDoc lately, I believe.

James Edward Gray II