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

[Reuben Thomas <rrt@...>]

On 28 February 2011 22:17, Axel Kittenberger <axkibe@gmail.com> wrote:
>> 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".

Indeed, something I'm trying to help rectify.

> 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.

But equally, if you're a developer using the code, you can (and
should) ask questions and report bugs when the documentation doesn't
match the code, or seems to be erroneous or incomplete. (This doesn't
really help much with luaposix, where there's no documentation,
admittedly.)

> 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.
> [cut]
> this gives me the
> flexibility to change the inner workings while having the metatable
> functions as luting to sustain a more stable API:

How does it give you any more flexibility than any other solution
exposing the same API?

-- 
http://rrt.sc3d.org