RDoc - run cpp first?

[Ross Bamford]

Hi,

Just wondering if there's a way to get Rdoc to run the C preprocessor
over .c files it's documenting? I like to use macros to define method
functions and so on, but I often run up against limitations of Rdoc wrt.
finding comments for functions and so on. Right now I end up doing:

/*
* rdoc comment
*/
static VALUE some_attr_setter(VALUE self, VALUE val) {
OBJ_SETTER(ruby_wrapped_type, val);
}

But I'd rather do:

/*
* rdoc comment
*/
OBJ_SETTER(some_attr_setter, ruby_wrapped_type, val);

which doesn't work. Another one I've found is:

/* rdoc comment */
#ifdef SOMETHING
rb_define_const(cSomeClass, "SOMETHING", INT2FIX(SOMETHING));
#else
rb_define_const(cSomeClass, "SOMETHING", INT2FIX(-1));
#endif

which ends up being documented twice, with both values, neither with the
attached comment.

Obviously there are workarounds but, as I say, I just wondered if this
was possible, or if there was a better way to approach these kinds of
problems.

Cheers,
Ross

 

[Ross Bamford]

Just wondering if there's a way to get Rdoc to run the C preprocessor
over .c files it's documenting?

Okay, that's my stupid question for this week over with. Obviously it
strips the comments...

Sorry about that.

 

[Jan Svitok]

Okay, that's my stupid question for this week over with. Obviously it
strips the comments...

Sorry about that.

It seems there is a switch to gcc's cpp that tell it to keep the
comments (-C). I'm not sure whether additional #lines won't confuse
RDoc anyway... There should be some similar switch for MSVC as well.

 

[Ross Bamford]

It seems there is a switch to gcc's cpp that tell it to keep the
comments (-C). I'm not sure whether additional #lines won't confuse
RDoc anyway... There should be some similar switch for MSVC as well.

Interesting - I missed that option. I just tried it out, and it seemed
to work quite well. It slows Rdoc down a bit (a lot more source to scan)
but the output is pretty good.

As Hugh pointed out though, it does expand a bit too much - constants
set with INT2FIX, for example, show their value as the expansion of the
macro. For me, though, that's a minor concern.

This is the script I used to test it:

#!/usr/local/bin/ruby
system('mkdir doctmp')

begin
incflags = File.read('Makefile')[/INCFLAGS\s*=\s*(.*)$/,1]

Dir['*.c'].each do |fn|
system("cpp -DRDOC_NEVER_DEFINED -C #{incflags} -o " +
"#{File.join('doctmp', File.basename(fn))} #{fn}")
end

system('rdoc --main=README doctmp/*.c README LICENSE')
ensure
system('rm -rf ./doctmp')
end
__END__

Cheers,