RDOC: several related modules in several C files


#1

Hi all!

I have a pretty large extension I want to document with RDoc.

The problem is, I have several files:

htmr_main.cpp:

rb_mHtmr = rb_define_module(“Htmr”);

htmr_constants.cpp:


rb_mHtmrConstants = rb_define_module_under(rb_mHtmr, “Constants”);

The problem with such organization: RDoc says “Enclosing class/module
‘rb_mHtmr’ for module Constants not known”.

I can:

  1. move the line “rb_mHtmr = …” to htmr_constants.cpp, but rb_mHtmr is
    used not only from this file.
  2. move the line “rb_mHtmrConstants = …” to htmr_main.cpp, but in this
    case all othre contents of htmr_constants.cpp is ignored by Rdoc.
  3. join all files of the extension into one huge file, but it will be
    ugly
    :frowning:

Was I miss something?

Thanks.

V.


#2

The problem with such organization: RDoc says “Enclosing class/module
‘rb_mHtmr’ for module Constants not known”.

I’ve done the following with my extensions:
while creating documentation, I’ve concatenated all data in one file and
rdoc is parsing one file.


#3

From: removed_email_address@domain.invalid [mailto:removed_email_address@domain.invalid] On Behalf
Of
Max L.
Sent: Friday, March 16, 2007 9:10 AM

The problem with such organization: RDoc says “Enclosing class/module
‘rb_mHtmr’ for module Constants not known”.

I’ve done the following with my extensions:
while creating documentation, I’ve concatenated all data in one file and
rdoc is parsing one file.

I’ve eventually found another solution: have added to each file some
additional definitions to make RDoc happy, and make them “invsible” to
compiler with #ifdef SOME_STRANGE_SYMBOL/#endif

It works.

(BTW, the solution to join all files to one can’t work for me in any
case,
as in my sources there are many other problems for RDoc, like shortcut
macro
for defining ruby methods, additional namespaces and so on).

V.


#4

as in my sources there are many other problems for RDoc, like shortcut
macro

These shortcuts seems to be one of the greatest problem. The only way to
bypass them is to use some sort of C->xml compilers in RDoc (to make it
very complicated), or to create some sort of explicit binding C
functions to ruby methods


#5

BTW, I’ve found even \t (Tab) symbol in sources confuses RDoc

Yes, RDoc seems to be a rather confusable thing =)
I think, that there is no use in trying to make a perfect RDoc for C
extensions, so You hack is OK. You can also make the following:
preprecess sources before RDoc-ing them. Thus, all You macroses will be
expanded to rb_define_method


#6

From: removed_email_address@domain.invalid [mailto:removed_email_address@domain.invalid] On Behalf
Of
Max L.
Sent: Friday, March 16, 2007 6:00 PM

as in my sources there are many other problems for RDoc, like shortcut
macro

These shortcuts seems to be one of the greatest problem. The only way to
bypass them is to use some sort of C->xml compilers in RDoc (to make it
very complicated), or to create some sort of explicit binding C
functions to ruby methods

Aha. I’ve ended with having something like

//real definition
DEF_METHOD(method, c_method, 1);

#ifdef MAKIN_RDOC_HAPPY // MAKIN_RDOC_HAPPY isn’t defined :slight_smile:

//fake definition
rb_define_method(rb_cMyClass, “method”, c_method, 1);

#endif

My DEF_METHOD definitons (even if they are many) looks much more DRY (I
have
to write only differing parts of each definition).

BTW, I’ve found even \t (Tab) symbol in sources confuses RDoc

V.