RDoc C parser needs improvement

I don't think I've mentioned here how frustrating RDoc's C parser can be. It's almost up there with SDL_mixer on the headache-o-meter, I swear.

I'll admit, the idea of automatically generating documentation from the code structure and comments in the source code is neat. And RDoc does a pretty good job of figuring out the structure of Ruby code. It's pretty smart at that, and it can figure out which class is located under which module, and which class in the parent of which subclass, and which mixin is included in which class, etc.

But it's not so great at figuring that stuff out in the code for extensions written in C, like Rubygame.

Partly that's because it's a harder task to tease the meaning out of the C code. It's also partly because the C parser doesn't have as many users (and thus fewer eyes for looking, and fewer hands for patching).

Whatever the reason, the C parser is a lot less polished than its Ruby-parsing counterpart. It's able to handle simple things decently: defining a module, defining a class, defining methods under that class, etc. But for more complex scenarios, it fails.

And it's fine that it can't figure out complicated stuff on its own. It wouldn't be reasonable to expect RDoc to handle every strange scenario perfectly. The problem I have is that there's very little you can do to help RDoc generate the correct documentation, except trying to avoid situations that it doesn't understand. (Designing code around the deficiencies of the documentation program? It's insane, but I have to admit I've done it in several places in Rubygame in the past.)

What I'd really like to do, is give meaningful hints to RDoc, to help it understand what's going on. For example, consider this C code, which I've recently written in the Surface class to make it include the NamedResource mixin:

rb_include_module( cSurface,
  rb_const_get(mRubygame, rb_intern("NamedResource")) );

RDoc's parser will not have a clue what's going on here, and that's understandable. But if there was a way to tell RDoc, "Hey, the Surface class includes Rubygame::NamedResource", it wouldn't need to figure out what the code means. I'd have more control over the documentation that's generated, and the output would be more meaningful and useful to the reader. Everybody would be shiny and happy.

Unfortunately, I don't think I have the time to learn RDoc's inner workings well enough to patch it to do such a thing. (Heck, I don't even have as much time to dedicate to Rubygame as I'd like.)

So my options right now are:

1. Jump through some hoops and pretend to define the NamedResource module again in a place that RDoc will remember it in this scope.
2. Write the module inclusion code in Ruby (and thus split my class definition across two files in two different languages).
3. Write a dummy sourcefile in Ruby with the documentation (this is what Chipmunk does).
4. Just put a note in the class documentation for Surface, mentioning that it includes the module.

I started using #1 years ago to make RDoc to correctly place all the classes inside the Rubygame module. But since it's not as important that RDoc know about the relationship between Surface and NamedResource, I'll probably end up using #4.

Besides the deficiencies in the C parser, there are some other things about RDoc (and automated documentation extraction in general) which displease me, but I've already wasted enough time ranting for one day. ;)