From: Ross Bamford <rossrt@...>
Date: 2006-11-25T19:48:38+09:00
Subject: Re: RDoc - run cpp first?

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.

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,
-- 
Ross Bamford - rosco@roscopeco.REMOVE.co.uk