[prog] APIs for dummies?

[meredydd at everybuddy.com]

> - If there's a string or pointer argument, what's the ownership?
yes Yes YES! This is one of my favourites too. It's even worse, of course,
when something *returns* a pointer - what's it to? Is it allocated
on-the-fly? If so, do I free() it myself, or is there a separate
deallocate function? If it's not, how long will it last? Is it static?
It's a good idea to indicate/force your policy with all *arguments* that
aren't affected being "const" (or equivalent), but watch your return
values. You can get a situation where, for example there's a plain char *
somewhere in the calling tree, and a const char * gets returned, and all
of a sudden you have to modify the *whole* heirarchy just because one
function returns const - either that or waste time making a copy of it at
runtime for no good reason.

These especially can be a real pain in the butt for projects which have to
weld several separate components together (*ahem*, can't you tell I speak
from experience?) - you sometimes have to hold or free pointers and
allocate copies to move from one scheme to another.

Meredydd