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 - rosco@roscopeco.REMOVE.co.uk
Okay, that's my stupid question for this week over with. Obviously it
strips the comments...
Sorry about that.
···
On Fri, 2006-11-24 at 22:41 +0900, Ross Bamford wrote:
Just wondering if there's a way to get Rdoc to run the C preprocessor
over .c files it's documenting?
--
Ross Bamford - rosco@roscopeco.REMOVE.co.uk
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.
···
On 11/24/06, Ross Bamford <rossrt@roscopeco.co.uk> wrote:
On Fri, 2006-11-24 at 22:41 +0900, Ross Bamford wrote:
> 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.
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,
···
On Sat, 2006-11-25 at 00:35 +0900, Jan Svitok wrote:
On 11/24/06, Ross Bamford <rossrt@roscopeco.co.uk> wrote:
> On Fri, 2006-11-24 at 22:41 +0900, Ross Bamford wrote:
>
> > 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.
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 - rosco@roscopeco.REMOVE.co.uk