add scaladoc for core api method, change readme typo.