[prog] APIs for dummies?

[Akkana Peck]

Jenn Vesperman writes:
> I will add one more thing:
> 
> DOCUMENT.

[ lots of good suggestions ]

> Hm. Anyone have any other pet peeves in not-fully-documented APIs and
> function libraries?

Oh, yes!

- If there's a string or pointer argument, what's the ownership?
  Will the routine allocate memory, and does the caller then own
  the memory and is expected to free it when it's done with it?
  Or is it passing back static memory, which might get overwritten
  later, so the caller should copy it if it's to be kept around
  for any length of time?  If it should be freed, what routine
  should be used?  This is one of the biggest source of memory
  leaks (and hence performance problems) in modern software.

- Jenn touched on this, but I'll get more specific:
  What is the function's return value if it succeeds?
  How does it indicate an error if something goes wrong?
  Will it modify its arguments (for instance, any pointer arguments)
  in the failure case?

  	...Akkana