Problem with rdoc and extensions

ruby-talk
1

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. :slight_smile:

-Charlie

2

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. :slight_smile:

-Charlie

3

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.

4

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

···

On Oct 4, 2004, at 18:36, Charles Mills wrote:

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?

5

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

···

On Dec 30, 2004, at 7:06 PM, rinconj wrote:

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.

6

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

-a

···

On Tue, 5 Oct 2004, Dave Thomas wrote:

On Oct 4, 2004, at 18:36, Charles Mills wrote:

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)

--

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

===============================================================================

7

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

···

On Oct 4, 2004, at 9:34 PM, Ara.T.Howard@noaa.gov wrote:

On Tue, 5 Oct 2004, Dave Thomas wrote:

On Oct 4, 2004, at 18:36, Charles Mills wrote:

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)

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