How can I make rdoc properly read method arguments from my c extension?

Question

all, I'm using rdoc to generate documentation for my Ruby code which contains C-extensions, but I'm having problems with my method arguments. Rdoc doesn't parse their names correctly and instead uses p1, p2 etc.

So, first off, my extensions are actually compiled as C++ so I have to use function definitions that look like this:

static VALUE 
MyMethod(VALUE self, VALUE flazm, VALUE saszm)
{
    return Qnil;
}

It looks like rdoc expects old style "C" definitions like this:

static VALUE
MyMethod(self, flazm, saszm)
    VALUE self;
    VALUE flazm;
    VALUE saszm;
{
    return Qnil;
}

Is there anyway I can make this work?

Answer 1

RDoc is completely clueless about argument names in C extensions*. This is how RDoc compiles the string of arguments:

meth_obj.params = "(" + (1..p_count).map{|i| "p#{i}"}.join(", ") + ")"

Changing your source formatting won't help.

To improve your documentation, you could use the call-seq directive. You can specify one or more ways to invoke your method, which will be used instead of the default method(p1, p2) stuff.

/*
 * call-seq:
 *   my_method(flazm, saszm) -> nil
 *   my_method(bunny) { |fluffy_ears| ... } -> true or false
 *
 * Method description here.
 */
static VALUE 
MyMethod(VALUE self, VALUE flazm, VALUE saszm)
{
    return Qnil;
}

* It is clueless about some other things as well. Regex-based "parsing" is very naive.