So, basically the consensus is that Rdoc is in need of some work, 
especially as regards the .c files, that online editing of the docs 
directly isn't required, but that the current ruby-doc doc browser is a 
bit crufty and could be done better and preferably without frames.

As regards improving the RDoc tool itself, I'm not really sure if I'm 
experienced enough to do that, but I'm willing to look at it at least.

At the very least, I think the output from the Rdoc tool could be better 
presented and organized on the web, which may be what James is working 
on, and we could bolt on a comment system to allow people to suggest 
improvements to the documentation or outline pitfalls with the 
particular function ( see an example here: 
http://www.php.net/manual/en/function.substr-replace.php ).

The RDoc format seems pretty full-featured, about the only thing I'd 
like to add would be a tag to define code snippets so they could be 
syntax-highlighted for the web (it looks like code snippets are just 
rendered in the typewriter style font at the moment).

As far as functionality goes Hugh mentioned call graphing, I guess that 
means showing that function X calls function Y which calls function Z?

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

To summarize, I'm thinking to scrap the online editing idea and just 
reformat the output of rdoc and add a comment system for each 
class/function/whatever. Also, assuming I can decipher the rdoc code, 
and I can decide on what to change/fix/add, some improvements could be 
done on rdoc itself.

James, could you fill me in on what you're working on as regards this 
whole thing, maybe we can pool our efforts on this...

Oh, it looks like I'm getting replies from ruby-talk and ruby-doc, 
anyone have any objections on moving this discussion to ruby-doc only 
now that there's a discussion going? The only problem is that ruby-doc 
doesn't seem to be publically archived anywhere like all the other ruby 
mailing lists are...

Anyway, thanks for the input guys, I really would like to whatever I can 
to help ruby out, and this seems as good a place as any to start :)

Andrew