> We must document these APIs asap (we should really be doing this as part of writing the code anyway).

+1