Re: How close to C do you make your binding?

[steve donovan <steve.j.donovan@...>]

On Thu, Jun 19, 2014 at 8:25 AM, Coroutines <coroutines@gmail.com> wrote:
> ... Even if the docs are great users get turned off
> if the docs aren't pretty or marked up in a way that makes them want
> to read the docs.

Alas, that's so true - people's expectations have changed, in the old
days they would be happy to have a few man pages.  Tough for those of
us whose ideas of web design fossilized in the late 20thC.

Earlier I raised the point of reaching an audience who is not fluent
in C.  But even if the user is fluent, and knows the C API, and even
if the Lua interface is faithful, there will be gaps.  I remember
having fun using some older GTK bindings, and constantly having to
check the original docs and apply a few transformation rules mentally.
Well then the Lua interface wasn't faithful, you might say.  But since
the languages are so different, there will always be impedance
mismatch.  The pyGTK people did it properly, but it was a lot of work,
and generally that's true: documentation is hard and not glamorous!

Writing copious examples is more entertaining than traditional docs
and works almost as well.  People say that tests make good
documentation, but this does not seem automatically true; often
they're practically unreadable because there's no narrative.

> ... On the whole it's easy to
> build over an unforgiving C interface to something friendlier in pure
> Lua, it's harder to do the reverse.

That's for sure.