Ruby Documentation

July 3, 2006 code 2 min read

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

This content is open source. Suggest Improvements.


avatar of Brandon Keepers I am Brandon Keepers, and I work at GitHub on making Open Source more approachable, effective, and ubiquitous. I tend to think like an engineer, work like an artist, dream like an astronaut, love like a human, and sleep like a baby.