break up instantiation API into three parts and better document function
signatures