problem with rdoc and extensions

[Charles Mills]

Hi,
I am trying to use rdoc to document a C extension. The file structure
of the extension is as follows:
ext.h
ext.c
ext_class1.c
ext_class2.c
ext_class3.c
...

where "EXT" is the module and "Class1", "Class2", etc are the classes
defined under "EXT".
So the name space looks like:
EXT
EXT::Class1
EXT::Class2
EXT::Class3
...


'ext.h' contains a global variable:
VALUE mEXT;
which is references the Ruby module EXT at runtime.

In 'ext_class1.c' (and friends) we have:

#include "ext.h"

/* ... */

void Init_EXT_Class1(void)
{
rb_define_class_under(mEXT, "Class1", rb_cObject);
/* define class methods ... */
}

In ext.c we have

#include "ext.h"

void Init_ext(void)
{
mEXT = rb_define_module("EXT");
Init_EXT_Class1();
Init_EXT_Class2();
Init_EXT_Class3();
/* ... */
}

So the problem is when documenting 'ext_class1.c' and friends rdoc
can't figure out what the variable 'mEXT' is (the module the classes
are defined under) and fails to document Class1 and friends.

Any solutions?
Putting everything in one .c file is not an option.

-Charlie

 

[Charles Mills]

Here I am replying to my own post...
I looked at the rdoc C parser, it doesn't look like rdoc maintains its
state between each .c file. Is this what is going on?

Made a few corrections to my last post:

Hi,
I am trying to use rdoc to document a C extension. The file structure
of the extension is as follows:
ext.h
ext.c
ext_class1.c
ext_class2.c
ext_class3.c
...

where "EXT" is the module and "Class1", "Class2", etc are the classes
defined under "EXT".
So the name space looks like:
EXT
EXT::Class1
EXT::Class2
EXT::Class3
...


'ext.h' contains a global variable:

extern VALUE mEXT;

which references the Ruby module EXT at runtime.

In 'ext_class1.c' (and friends) we have:

#include "ext.h"

/* ... */

void Init_EXT_Class1(void)
{
rb_define_class_under(mEXT, "Class1", rb_cObject);
/* define class methods ... */
}

In ext.c we have

#include "ext.h"

VALUE mEXT;

void Init_ext(void)
{
mEXT = rb_define_module("EXT");
Init_EXT_Class1();
Init_EXT_Class2();
Init_EXT_Class3();
/* ... */
}

So the problem is when documenting 'ext_class1.c' and friends rdoc
can't figure out what the variable 'mEXT' is (the module the classes
are defined under) and fails to document Class1 and friends.

Any solutions?
Putting everything in one .c file is not an option.

-Charlie

 

[Dave Thomas]

Here I am replying to my own post...
I looked at the rdoc C parser, it doesn't look like rdoc maintains its
state between each .c file. Is this what is going on?

That's correct - it would be inappropriate to do that when RDoc is used
(for example) to document all the Ruby extensions.

I'm not sure of an easy way to handle your particular problem, apart,
perhaps from an ugly cheat. In each .c file that defines classes based
on the external module, put a definition of the module variable and the
define_module line in an ifdef's out chunk of code (see, I said it was
ugly)


Cheers

Dave

 

[Ara.T.Howard]

That's correct - it would be inappropriate to do that when RDoc is used
(for example) to document all the Ruby extensions.

I'm not sure of an easy way to handle your particular problem, apart,
perhaps from an ugly cheat. In each .c file that defines classes based
on the external module, put a definition of the module variable and the
define_module line in an ifdef's out chunk of code (see, I said it was
ugly)

how about using cpp, or cat even, to inline all your c sources and the
rdoc'ing one giant source file?

-a
--
===============================================================================
| EMAIL :: Ara [dot] T [dot] Howard [at] noaa [dot] gov
| PHONE :: 303.497.6469
| A flower falls, even though we love it;
| and a weed grows, even though we do not love it.
| --Dogen
===============================================================================

 

[Charles Mills]

how about using cpp, or cat even, to inline all your c sources and the
rdoc'ing one giant source file?

That is a great idea. Tried it and it works well. You obviously don't
get a list of all the .c files in the project, but that is not really a
problem (if it become one Daves idea looks like it solves that).

Thanks for the help,
Charlie

 

[Dave Thomas]

I just encountered the same problem with libpcap-ruby.
I guess it's not much of a problem to cat all the files into one, but
it
certainly is something rdoc should improve with future releases.

I missed the original -- what's the issue?