RDoc and generated classes

[Jamis Buck]

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?

- Jamis

--
Jamis Buck
(e-mail address removed)
http://www.jamisbuck.org/jamis

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

 

[Dave Thomas]

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...

Cheers

Dave

 

[Jamis Buck]

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
(e-mail address removed)
http://www.jamisbuck.org/jamis

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