polished text, fixed api docs, fixed json, minor DRY refactor