From: Jamis Buck <jgb3@...>
Date: 2004-09-10T01:09:01+09:00
Subject: Re: RDoc and generated classes

Dave Thomas wrote:
> 
> On Sep 9, 2004, at 10:37, Jamis Buck wrote:
> 
>> I've got a set of about 26 classes that are all very similar, and I'm 
>> using a loop (containing _n_ lines of code) in some C code to create 
>> them (instead of using 26*n lines of code). Naturally, RDoc can't 
>> parse those definitions out, but I'd like them documented. For now, 
>> I'm doing something like this:
>>
>>   #ifdef DONT_DEFINE___RDOC_PURPOSES_ONLY
>>     x = rb_define_class_under( MyModule, "Class1", ParentClass )
>>     x = rb_define_class_under( MyModule, "Class2", ParentClass )
>>     ...
>>     x = rb_define_class_under( MyModule, "Class26", ParentClass )
>>   #endif
>>
>> And then I'm using "Document-class:" comments to document each class 
>> individually. It seems to work, but I'm wondering: is there a better 
>> way to do this?
> 
> 
> I'm resisting the temptation to let RDoc run code during the 
> documentation process: I don't want it to become a vector for 
> introducing problems into user's machines. So for now I think your way 
> is probably the best.
> 
> Except... would it help to be able to say
> 
> * Document-class:  A, B, C, D, E...
> 

Probably not, at least, not in my case. Each class has different 
documentation, so I still need to document each one separately.

Another issue, though: suppose I do the following in my Init_xxx function:

   mExceptions = rb_define_module_under( mSQLite, "Exceptions" );

This creates a new module SQLite::Exceptions which I want to put all the 
exceptions under. In this instance, mExceptions is a global variable. 
However, when I do my little trick (as described above):

   x = rb_define_class_under( mExceptions, "Class1", ParentClass )

I get RDoc errors "Enclosing class/module 'mExceptions' for class Class1 
not known". If I get a chance I'll delve into it and see if I can submit 
a patch. Just thought you'd like a bug report in the meantime. :) 
(Incidentally, the #ifdef'd section is NOT in the Init_xxx function... I 
hadn't thought to try that until just now. I'll try it later and see if 
that helps at all.)

Thanks, Dave!

- Jamis

> Cheers
> 
> Dave
> 
> 
> .
> 


-- 
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis

"I use octal until I get to 8, and then I switch to decimal."