minor formatting changes, added some comments to some api code, etc.
wip - partial cleanup of apis to reflect recent work.