RDoc and generated classes

Discussion in 'Ruby' started by Jamis Buck, Sep 9, 2004.

  1. Jamis Buck

    Jamis Buck Guest

    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

    http://www.jamisbuck.org/jamis

    "I use octal until I get to 8, and then I switch to decimal."
     
    Jamis Buck, Sep 9, 2004
    #1
    1. Advertisements

  2. Jamis Buck

    Dave Thomas Guest

    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
     
    Dave Thomas, Sep 9, 2004
    #2
    1. Advertisements

  3. Jamis Buck

    Jamis Buck Guest

    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

    --
    Jamis Buck

    http://www.jamisbuck.org/jamis

    "I use octal until I get to 8, and then I switch to decimal."
     
    Jamis Buck, Sep 9, 2004
    #3
    1. Advertisements

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.