From: Sean O'Halpin <sean.ohalpin@...>
Date: 2008-12-16T00:41:07+09:00
Subject: Re: Standardizing FFI based wrappers

On Mon, Dec 15, 2008 at 3:06 PM, Luc Heinrich <luc@honk-honk.com> wrote:
> One thing I noticed while doing this, for example, is that you still have to
> refer to the original zlib header(s) to figure out what the function
> parameters are exactly, since the attach_function calls only mention the
> types. You would probably still have to check the documentation for behavior
> explanations but if the parameter names would at least be available
> somewhere it would probably make things easier.
>
> So is it ok to simply redirect the wrapper user to the library headers ? Or
> do we want a standard way to comment the function wrappers too ?

Surely one of the ideas behind providing thin wrappers is that the
existing C-oriented documentation will suffice with a little
translation.

Better to put effort into documenting common C to Ruby FFI idioms to
help in that translation across all FFI wrappers IMHO.

So perhaps FFI docs could contain pointers to original docs plus notes
on any significant departures from a straight transliteration and how
to handle tricky arguments?

Regards,
Sean