a bit of doc, helper functions, and some slight go idom changes on api