One of my (few) frustrations transitioning from Java to Ruby has been accessibility of library documentation. The only thing I miss about Java and a statically typed language is that almost all the documentation you need is available through the IDE. There is almost no uncertainty about what methods are available, what a method returns or what parameters it takes. There are other means to get to this information in Ruby, but I haven't been able to find a central, easily accessible source for documentation.
HTML output of RDoc is good; I can open up ruby-doc.org and api.rubyonrails.org in a browser, but that only addresses part of the problem. How do I know what methods are available on a String in Rails, without having to wade through the Rails HTML RDoc for the 5 extensions to the String class? IRB (or
script/console) helps by allowing me just to do
"".methods.sort, but that's by no means accessible, and if I want more information on a method, there's no way to link to it.
The other problem that I have consistently wrestled with is documentation for gems. This is probably old-hat to many Rubyists, but I just discovered
gem\_server, which helps immensely.
gem\_server starts up WebBrick on port 8808 and provides HTML RDoc for all the gems you have installed.
Since having all this available in an editor is probably a pipe dream (TextMate is good, but it's not that good), what are my options? Maybe this would be a good candidate for a Rails plugin that would expose a controller with searchable documentation for the current app, using some Ruby magic to merge all the documentation together.
update: I've posted some more thoughts on this subject in Ruby Documentation Redux.