I'll add something about this to the API doc.  PR imminent.