# RDoc - run cpp first?

**URL:** <https://www.ruby-forum.com/t/rdoc-run-cpp-first/77126>\
**Category:** Ruby\
**Created:** [November 24, 2006, 2:41pm UTC](https://www.ruby-forum.com/t/rdoc-run-cpp-first/77126 "2006-11-24T14:41:56Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![ross\_b](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/8edcca/32.png) [@ross\_b](https://www.ruby-forum.com/u/ross_b)\
**Post date:** [November 24, 2006, 2:41pm UTC](https://www.ruby-forum.com/t/rdoc-run-cpp-first/77126/1 "2006-11-24T14:41:56Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![ross\_b](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/8edcca/32.png) [@ross\_b](https://www.ruby-forum.com/u/ross_b)\
**Post date:** [November 24, 2006, 4:12pm UTC](https://www.ruby-forum.com/t/rdoc-run-cpp-first/77126/2 "2006-11-24T16:12:06Z")

</div>

On Fri, 2006-11-24 at 22:41 +0900, Ross B. 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.

---

<div class="post-metadata">

**Author:** ![ross\_b](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/8edcca/32.png) [@ross\_b](https://www.ruby-forum.com/u/ross_b)\
**Post date:** [November 24, 2006, 4:38pm UTC](https://www.ruby-forum.com/t/rdoc-run-cpp-first/77126/3 "2006-11-24T16:38:10Z")

</div>

On 11/24/06, Ross B. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> On Fri, 2006-11-24 at 22:41 +0900, Ross B. 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.

---

<div class="post-metadata">

**Author:** ![ross\_b](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/r/8edcca/32.png) [@ross\_b](https://www.ruby-forum.com/u/ross_b)\
**Post date:** [November 25, 2006, 11:48am UTC](https://www.ruby-forum.com/t/rdoc-run-cpp-first/77126/4 "2006-11-25T11:48:48Z")

</div>

On Sat, 2006-11-25 at 00:35 +0900, Jan S. wrote:

> 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,