[Nitro] RDog ping

James Britt james.britt at gmail.com
Tue Jun 20 13:35:41 EDT 2006

I've been busy, but still interested in getting a better Ruby API search 
and comment tool up on ruby-doc.org.

Both RDog and Rannotate take a similar approach: use rdoc to create a 
set of base files, then feed those files into some processor.  Rannotate 
has rdoc generate SQL, and then the rest is basically a Rails app that 
allows for searching and commenting.

RDoc goes for a yaml intermediate format, which I find more interesting, 
because it seems like it would lend itself to assorted data manipulation 
tools.  But, last I checked, it was barfing on various files (or at 
least had issues when I tried running it over the Ruby core).

However, there was another Make RDoc Better project, Rue, that included 
a YAML output formatter.  (Rue created nice-looking rdoc pages that uses 
  XMLHttpRequest for neat-o Web 2.0 goodness.  Quite nice, really.)

I took a look at the YAML it creates, and it appears, at first glance, 
complete.  (I've spent time trying to get Rdoc to emit useful XML; the 
default XML is heavy with presentation markup and light on semantic 

I also ran the rue template over the core Ruby source; it ran quite 
fast, and produce an 88K+ YAML file.  (I've not inspected it for 

So the rue template may solve at least one issue I've seen with RDog. 
If the YAML is complete (meaning it has both all the basic for all 
classes, modules, methods, etc, as well as data required to disambiguate 
when a method is part of the base class definition, and when it gets 
added when loading a module; Rannotate, for example, does not seem to 
manage this distinction) then the next step is using the corresponding 
Ruby objects to drive a viewing/searching/commenting system.


The Rue project seems to have vanished, but I have the files if anyone 
is interested in playing around.

(One thing I like about Og is that, once you have Ruby objects, you have 
automagical data persistence; that part Just Happens.  And the YAML 
format gives us at least the basis for a set of Ruby objects that define 
API data.)

James Britt

http://www.ruby-doc.org       - Ruby Help & Documentation
http://www.artima.com/rubycs/ - The Journal By & For Rubyists
http://www.rubystuff.com      - The Ruby Store for Ruby Stuff
http://www.30secondrule.com   - Building Better Tools

More information about the Nitro-general mailing list