The CAPI Manifesto

[Walter Bright]

On 10/16/2011 10:24 PM, Gor Gyolchanyan wrote:
> I think there might be a few tricks to improve the C API without
> adding any new code.
> For example, replace by-pointer parameter declarations with _out_
> parameters when applicable (the underlying function signature is the
> same), replace const parameters with in parameters, etc.
> This won't change the C API a single bit (won't even add new code),
> but will vastly improve readability and sometimes safety of the API.
> In other cases, some minor additions could be made, for example:
> libjpeg provides API to register error handlers, instead of setting
> errno and such. Those kind of situations could be used to throw
> exceptions. It only takes a static this() and a few lines of code.
> In case those kind of modifications/additions are made, there could be
> a standard way to disable them and use the original version.

If you want to add a layer on top of the C API, that would be fine. std.zlib is 
an example of that.

But the idea of CAPI is NOT to add a layer. Not fix, extend, refactor, improve, etc.

Just the thinnest possible direct calls to the C API. Any improvements, fixes, 
whatever, should be a separate project.

I know the urge to do these fixes can be overpowering, but they end badly every 
time. It's like trying to mix the language's lexer up with the semantic analysis :-)

They really are better off being separate and distinct.

For one thing, it makes the inevitable maintenance *FAR* easier, as those C APIs 
will change. Updating the corresponding D module becomes simple then - just a 
line by line comparison and tweaking. There would be no tearing of hair and 
rending of garments.

For another it means you'll have to regenerate the C documentation, but with all 
the changes you made. Then, as the C guys improve their documentation, your 
layer falls behind, gets neglected, and finally sucks in comparison.