Re: Public APIs and documentation (was: Re: LuaJIT FFI __gc metamethod?)

[Axel Kittenberger <axkibe@...>]

> This means that you need documentation which actually being read by
> developers.  Is this feasible in practice, outside high-integrity
> systems and other niches?

This means that you actually write proper documentation. A barrier
~90% of OpenSource projects do not get over.(Altough the percentage
goes up in the major ones, which are actually a few percent). This
barrierfail includes major lua libraries like e.g. luaposix that just
states "read the posix standard and the luaposix source code".

Even if you manage that barrier, it requires you to keep the
documentation up to newest state. So even if you have documentation,
its quite normal the source base evolves faster than the docs.

And even for the most ambigious documentions, there is repeatedly an
uncertainy if one minuscule feature is really an "undocumented
feature", as in, use at your own risk, or is just something thats more
forgotten to be mentioned in the documentation and actually expected
to be API.

In Lsyncd I give the userscripts completly opaque handlers. Empty
tables with the metatable set to behave like what is expected from the
API, for the core the handles are a keys to a weak table that contains
all the information what they stand for. This not that I distrust the
scripters, they have all the core source anyway and can open it anyway
they want, but beside having a clearcut API, this gives me the
flexibility to change the inner workings while having the metatable
functions as luting to sustain a more stable API: