RDoc and generated classes

ruby-talk
1

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
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis

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

2

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

···

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?

3

Dave Thomas 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. :slight_smile: (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

···

On Sep 9, 2004, at 10:37, Jamis Buck wrote:

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