We attempt to parse C extension files. Basically we look for the standard
patterns that you find in extensions: rb_define_class,
rb_define_method and so on. We also try to find the corresponding C
source for the methods and extract comments, but if we fail we don't worry
too much.
The comments associated with a Ruby method are extracted from the C comment
block associated with the routine that implements that method,
that is to say the method whose name is given in the
rb_define_method call. For example, you might write:
/*
* Returns a new array that is a one-dimensional flattening of this
* array (recursively). That is, for every element that is an array,
* extract its elements into the new array.
*
* s = [ 1, 2, 3 ] #=> [1, 2, 3]
* t = [ 4, 5, 6, [7, 8] ] #=> [4, 5, 6, [7, 8]]
* a = [ s, t, 9, 10 ] #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
* a.flatten #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
*/
static VALUE
rb_ary_flatten(ary)
VALUE ary;
{
ary = rb_obj_dup(ary);
rb_ary_flatten_bang(ary);
return ary;
}
...
void
Init_Array()
{
...
rb_define_method(rb_cArray, "flatten", rb_ary_flatten, 0);
Here RDoc will determine from the
rb_define_method line that there's a method called "flatten" in
class Array, and will look for the implementation in the method
rb_ary_flatten. It will then use the comment from that method in the HTML
output. This method must be in the same source file as the
rb_define_method.
C classes can be diagramed (see /tc/dl/ruby/ruby/error.c), and RDoc integrates C and Ruby source
into one tree