The Ruby Explorer – Code Navigation Tool
One of the big problems I have when programming Ruby is finding information. I seem to spend half my time searching in books, scrolling through online documentation – even hunting through the source code of the Ruby library.
One of the things we wanted in Ruby In Steel was some way of getting at the documentation of classes, modules and methods without going to all that effort. To a large extent, our Tooltip documentation deals with this problem. Hover your mouse over a class name such as Hash or a method such as sort and its RDoc documentation will pop up in a tooltip.
For more on tooltips see the entry on QuickInfo and RDoc
That’s all very well if you just want to see documentation for a single class or method. But sometimes you want to view the actual code too. One way of doing this is by selecting ‘Go To Definition’ from a popup menu. This will take you to the place in which the selected class or method (or, indeed, variable) was first defined – whether in your own code or in the standard Ruby Library.
But even when you do this you are still restricted to working with, at most, one class at a time. True, once you go to the file in which the class defined, you can easily scroll down to find its methods. Even so, there are still occasions when what you really want is a reference to all the classes and methods available. The simple fact of the matter is that, in spite of our RDoc tooltips, in spite of our ‘Go To Definition’, there were still far too many occasions when I found myself flipping through books and online documentation in search of particular classes and methods. Eventually we decided that we really need to have some kind of index of Ruby classes built right into our IDE. Which is why we created The Ruby Explorer.
- The Ruby Explorer
Put simply, The Ruby Explorer is a tree-structured hierarchy in which the classes form the main branches and their methods form the sub-branches. Double-click a class or a method and the Ruby source code (if available) and RDoc documentation will be loaded into an editor window.
Let me be honest about this. Initially, the Ruby Explorer was intended for our own use only. We didn’t plan to include it in the final product. But over time, we discovered that we were relying open it so much, not only to navigate the code and documentation of the Ruby class libraries, but also to navigate the code in our own projects (your own classes and methods are added to the Explorer as you write them).
There was one niggly little problem we had to solve when using The Ruby Explorer to browse the standard class library: most of the code is written not in Ruby but in C. Apart from the fact that many Ruby programmers may not be sufficiently familiar with C to make head or tail of the C code, The Ruby Explorer itself is not a multi-language browsing tool. It only ‘understands’ Ruby. At first we thought we’d just have to learn to live with this limitation and display an error message if the code of a certain class happened to be written in C. The trouble is that so much of the Ruby library is written in C that this limitation would have severed crippled The Ruby Explorer.
Eventually we decide on a compromise: when real Ruby code is available for a class, The Ruby Explorer will load up that code; when only C-code is available, it will display the RDoc documentation from the original source code plus a pseudo-Ruby version of the class or method declaration. It’s not a perfect solution. But short of persuading Matz and his colleagues to rewrite the entire class library in Ruby (a suggestion which, I have a feeling, is unlikely to meet with a warm response), I think this offers a reasonable compromise between code and documentation navigation.
All I can say for sure is that, in the time I’ve been using The Ruby Explorer, my Ruby reference books have remained unthumbed and the online Ruby documentation has remained unperused ;-) .
|Note: RDoc ToolTips, Go To Definition and The Ruby Explorer are features of the Developer Edition of Ruby In Steel only.|