On Sun, Nov 13, 2005 at 01:19:35PM +0900, Eric Hofreiter wrote:
> Haha, I'm not sure whether you're serious or not, but the readme.ext and 
> pickaxe book are not adequate documentation. 

The latter's purpose was never intended solely to document the C extension
API for Ruby. The former is a convenience file that doesn't get much
attention.

> They'll get you started, but there are quite a few API's that are not 
> even mentioned at all, or if so only briefly.  

Not that many that you can actually call from a C extension, although tons
of internal ones for Ruby's own use only.

> An example would be the -1 calling sequence, which the readme.ext 
> describes, but it does not mention anything at all about formatting 
> the args until the appendix. 

So... it does describe it? I'm confused.

At any rate, page 292 of Programming Ruby, 2nd Edition describes what you 
are referring to in blindingly insightful detail. See the section entitled 
"API: Defining Methods".

> When I think of documentation, I think of listing a description for 
> every API that there is telling you everything you need to know when 
> using it.  

Certainly, the C extension docs are incomplete. No one is arguing against
that sentiment. But Ruby itself is pretty small and easily grepped for
things. (since they use the utterly repugnant C style that has function
names starting at the beginnings of lines) For example:

adidas~/code/ruby-1.8.3> grep -rn '^rb_thread_select' *
eval.c:10682:rb_thread_select(max, read, write, except, timeout)
adidas~/code/ruby-1.8.3>

Great for grepping, bad for writing. But, since you're not ruby-core, that
won't really be an issue.

> I'm not trying to complain; 

You are.

> obviously C extensions aren't a necessity for ruby,

Sometimes they are.

> it's just that trial and error is not a fun way to make a simple program.

C extensions aren't supposed to be for simple programs. That's what Ruby
is for ;-)

-- 
Toby DiPasquale