From: Robert Klemme <bob.news@...>
Date: 2005-06-08T01:20:27+09:00
Subject: Re: Could Ruby-doc be better? -- Proposal for a better system.

Lothar Scholz wrote:
> Hello Andrew,
>
>> As far as functionality goes Hugh mentioned call graphing, I guess
>> that means showing that function X calls function Y which calls
>> function Z?
>
> Don't forget Class Hierarchy Graphs.

Yep, I also think documentation of inheritance hiearchies could be better.

>>> Yes but the main problem is the bad implementation of RDOC which
>>> is not able to merge different "rdoc" runs into one "documentation
>>> repository". So if somebody want to spend time i think it's much
>>> better to do write a program that is using a good documentation
>>> database which allows addition and removal of documentation
>>> subtrees.
>
>> I'm not really sure what lothar means here, is he proposing that rdoc
>> should be able to resolve conflicts between different versions of
>> ruby its run against?
>
> I would like to see exactly one location where information about all
> libs and internal structures are stored. At the moment it is
> fragmented. You have some docs about "activerecord" here and some of
> the "actionmailer" there but no overall structure.

+1 Definitely!

> I think we should also go away from the idea to generate HTML files.
> Instead we should run a rdoc server and generate documentation on
> demand as this allows much better interaction and things like search
> functionality. Choosing HTML was just a lazy on in my opinion an old
> fashioned idea.

-1 I prefer static HTML files as these don't use extra resources; it's
also easier to do for multiple platforms.  I rather seldom feel the need
for a search functionality - and in these rare cases find-grep does the
job quite well.  My 0.02 EUR...

As a compromize there could be an IRB module that retrieves / generates
documentation on the fly.

Kind regards

    robert