- updated API doc to fix typos and add clarity/specifics