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

[Reuben Thomas <rrt@...>]

On 28 February 2011 21:26, Florian Weimer <fw@deneb.enyo.de> wrote:
>
> This means that you need documentation which actually being read by
> developers.

No, that just means that developers who don't read the documentation
don't get to complain when their code breaks.

It helps if the documentation is up-to-date, accurate, well-written,
easy to find, and attractive to read, but provided it meets at least
minimum standards, then you can feel justified in making whatever
changes you like that don't break the published APIs.

There are always exceptions to this (e.g. hacks that are sanctioned by
long usage, perhaps to provide functionality not available through the
public API) and of course you don't want to annoy users just for the
sake of it. But equally there's no reason to feel tied down by past
implementation details (or why have an API at all?).

-- 
http://rrt.sc3d.org