Goodbye Document-class! (And other RDoc improvements)

by Daniel Berger

Over the last couple of Ruby releases I've made some improvements (with Eric Hodel's help and blessing) to RDoc for C extensions that I thought I would share with you. If you write C extensions with Ruby then keep reading. If you don't do C and/or don't care that much about RDoc, this post may not be that interesting for you. :)

3 Comments

Jacob Fugal
2007-03-29 08:31:47
I'm curious about that last example, it seems the repetition of "1.2.0" in the source and then again in the docstring is less than ideal. My C is very rusty, but don't C #defines work through textual replacement during a preprocessing stage? Does that replacement include inside comments? Is that stage performed before the RDoc is gleaned out? If all three are true, you could do something like:


/* FOO_VERSION: The version of this package */


Alas, I fear that even if my memory on the first two is correct, the third probably is not true.


Not necessarily a change request, but something to think about...

Daniel Berger
2007-03-29 10:28:49
Jacob, RDoc just reads over the source file and parses it - there's no compilation involved if that's what you mean. However, in theory I could parse the files, look for rb_define_const, find the matching #define value, and set it that way.


But, that approach has several problems. First and foremost, there's no guarantee that the the #define is in the same file as the main source file. If not, I would have to scan *all* of the included header files looking for the proper value - how would I know where those are located? Second, dealing with anything except strings and numbers would be problematic. I would have to setup rules for the conversion functions, e.g. rb_str_new2 means it's a string, INT2FIX means it's a number, etc. Thirdly, it wouldn't work for anything but simple macro definitions, e.g. #define VERSION foo(x(y)). While that may not be an issue in practice, it's something to consider. Then there's the issue of conditional constants, which in fact, isn't handled currently, and can't be really, without resorting to a compile step of some sort.


It's not that it isn't possible to do what you want, it's just that it's way, WAY more effort than it's worth in my opinion.

Gregory
2007-03-29 11:43:42
Daniel,


Welcome to the ORA blog, and cool post. Nice Hardcore Stuff :)