Forum: Ruby RDOC: several related modules in several C files

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
2c7c807a1df0c76a8fc823c709b501a9?d=identicon&s=25 Victor "Zverok" Shepelev (Guest)
on 2007-03-06 17:41
(Received via mailing list)
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
:(

Was I miss something?

Thanks.

V.
143c67bc66364c543e85bc907717a8ab?d=identicon&s=25 Max Lapshin (max-lapshin)
on 2007-03-16 08:10
> 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.
2c7c807a1df0c76a8fc823c709b501a9?d=identicon&s=25 Victor "Zverok" Shepelev (Guest)
on 2007-03-16 16:52
(Received via mailing list)
From: list-bounce@example.com [mailto:list-bounce@example.com] On Behalf
Of
Max Lapshin
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.
143c67bc66364c543e85bc907717a8ab?d=identicon&s=25 Max Lapshin (max-lapshin)
on 2007-03-16 16:59
> 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
2c7c807a1df0c76a8fc823c709b501a9?d=identicon&s=25 Victor "Zverok" Shepelev (Guest)
on 2007-03-16 17:11
(Received via mailing list)
From: list-bounce@example.com [mailto:list-bounce@example.com] On Behalf
Of
Max Lapshin
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 :)

//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.
143c67bc66364c543e85bc907717a8ab?d=identicon&s=25 Max Lapshin (max-lapshin)
on 2007-03-16 17:15
> 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
This topic is locked and can not be replied to.