Over the last couple of Ruby releases I’ve made some improvements (with Eric Hodel’s help and blessing) to RDoc for C extensions that I thought I would share with you. If you write C extensions with Ruby then keep reading. If you don’t do C and/or don’t care that much about RDoc, this post may not be that interesting for you. :)

First, and most significantly, you no longer need to use the “Document-class” directive for source files that contain multiple classes and/or classes that don’t match the ‘xxx’ portion of ‘Init_xxx’. Prior to 1.8.6, for example, you might have something like this:

/*
 * Document-class: Top
 *    This is the Top namespace.
 */

/*
 * Document-class: Bar
 *    This is the Bar class
 */

/*
 * Document-class: Baz
 *    This is the Baz class.
 */

void Init_foo(){
   VALUE mTop, cBar, cBaz;
   mTop = rb_define_module("Top");
   cBar = rb_define_class_under(mTop, "Bar", rb_cObject);
   cBaz = rb_define_class_under(mTop, "Baz", rb_cObject);
}

I thought that having to explicitly document classes and modules outside of the Init_xxx function using special directives like that was ugly, so I dug into the rdoc source (scary!) and figured out to get this working. The short of it is that you can document your classes and modules in a manner that is much more in line with the way rdoc works for other C elements:

void Init_foo(){
   VALUE mTop, cBar, cBaz;

   /* This is the top namespace */
   mTop = rb_define_module("Top");

   /* This is the Bar class */
   cBar = rb_define_class_under(mTop, "Bar", rb_cObject);

   /* This is the Baz class */
   cBaz = rb_define_class_under(mTop, "Baz", rb_cObject);
}

This is a much nicer DWIM approach in my opinion. No special directives required.

The second improvement was a minor one. In pure Ruby you can have “personal comments” in methods that won’t be picked up in the rdoc by using “–” to delineate them:

# This is the foo method. There are many like it but this one is mine.
#--
# This was a major pain to implement for MS Windows.
def foo
   "hello"
end

In the above example the comment “This was a major pain to implement for MS Windows” is not picked up for the final rdoc output. Prior to Ruby 1.8.5 there was no similar mechanism for C extensions. Now, however, you can use the same approach:

   /*
    * This is the foo method. There are many like it but this one is mine.
    *--
    * This was a major pain to implement for MS Windows.
    */

The last thing I’ll mention is an improvement in the way constants are documented. Prior to 1.8.6 the constant definitions were parsed literally because rdoc has no way of knowing what a constant C value is. For example, if you had something like this:

#define FOO_VERSION "1.2.0"

void Init_foo(){
   VALUE cFoo = rb_define_class("Foo", rb_cObject);

   /* The version of this package */
   rb_define_const(cFoo, "VERSION", rb_str_new2(FOO_VERSION));
}

The end result would be “VERSION = rb_str_new2(FOO_VERSION)”. Not what we want. Now, however, you can specify the literal value yourself by using the “value: comment” syntax:

#define FOO_VERSION "1.2.0"

void Init_foo(){
   VALUE cFoo = rb_define_class("Foo", rb_cObject);

   /* 1.2.0: The version of this package */
   rb_define_const(cFoo, "VERSION", rb_str_new2(FOO_VERSION));
}

Enjoy!